Pular para o conteúdo principal

Diretório

O conjunto de endpoints a seguir é responsável pela gestão de Diretório.


Criar vínculo​

Endpoint para criar um novo vínculo de chave com conta transacional.

Idempotência

A operação de criação de vínculo é idempotente. Isso significa que é seguro realizar uma nova tentativa em caso de falhas temporárias, como erros de conexão ou término abrupto de processos. A resposta retornada para uma requisição repetida é equivalente à resposta dada à primeira requisição processada.

Para garantir a idempotência da operação, a requisição tem um campo x-request-id nos headers. Esse campo é um UUID versão 4 e deve ser único no contexto de um mesmo participante. O x-request-id fica associado ao vínculo criado e é usado no cálculo do seu CID.

Uma requisição de criação é considerada repetida quando o CID do vínculo contido na requisição já existe no DICT.

POST /dict/entries
Requer autorização para o escopo: keys.ind.write


Requisição

{
  "entry": {
    "account": {
      "accountNumber": "0007654321",
      "accountType": "cacc",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00Z",
      "participant": "12345678"
    },
    "key": "+5561988880000",
    "keyType": "phone",
    "owner": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "type": "natural_person"
    }
  },
  "reason": "user_requested",
  "requestId": "a946d533-7f22-42a5-9a9b-e87cd55c0f4d"
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

// Natural Person Owner
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "key": "11122233300",
    "keyType": "CPF",
    "account": {
      "participant": "12345678",
      "branch": "0001",
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "openingDate": "2010-01-10T03:00:00.000Z"
    },
    "owner": {
      "type": "NATURAL_PERSON",
      "taxIdNumber": "11122233300",
      "name": "João Silva"
    },
    "creationDate": "2019-11-18T03:00:00.000Z",
    "keyOwnershipDate": "2019-11-18T03:00:00.000Z"
  }
}

Consultar vínculo​

Endpoint para obter um vínculo contendo os detalhes de conta transacional associados a uma chave de endereçamento.

Limitação de requisições

A consulta a chaves está sujeita à política de limitação (rate-limiting) de requisições. A limitação funciona com base em cabeçalhos enviados na requisição. Os cabeçalhos de requisição são obrigatórios para todos os tipos de chaves.

O parâmetro End-User-Document é o identificador do usuário final e é usado para aplicar as políticas de limitação com escopo de usuário. Deve ser preenchido com o CPF ou CNPJ (apenas dígitos), a depender do tipo da entidade titular da conta pagadora.

Estatísticas

Através do parâmetro opcional IncludeStatistics, é possível indicar se as informações de contadores antifraude devem ou não ser incluídas na resposta.

GET /dict/entries/:key
Requer autorização para o escopo: keys.ind.read


Requisição

A requisição enviada para esse endpoint não precisa de um body, apenas os cabeçalhos de autorização OAuth, parâmetros e o certificado da conta.

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

// Legal Person
{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "OpenClaimCreationDate": "2023-01-01T10:00:00.000Z",
    "account": {
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00Z",
      "participant": "12345678"
    },
    "creationDate": "2023-01-01T10:00:00.000Z",
    "key": "11122233300",
    "keyOwnershipDate": "2023-01-01T10:00:00.000Z",
    "keyType": "cpf",
    "owner": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "tradeName": "Stark Industries",
      "type": "NATURAL_PERSON"
    }
  },
  "responseTime": 0
}

OU

// Legal person includes statistics
{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "OpenClaimCreationDate": "2023-01-01T10:00:00.000Z",
    "account": {
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00Z",
      "participant": "12345678"
    },
    "creationDate": "2023-01-01T10:00:00.000Z",
    "key": "11122233300",
    "keyOwnershipDate": "2023-01-01T10:00:00.000Z",
    "keyType": "cpf",
    "owner": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "tradeName": "Stark Industries",
      "type": "NATURAL_PERSON"
    }
  },
  "keyStatistics": {
    "entries": {
      "distinctAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "fraudMarkers": {
      "applicationFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "distinctFraudReporters": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "muleAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "otherFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "scammerAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "totalFraudTransactionAmount": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "unknownFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "infractionReports": {
      "openReports": 0,
      "openReportsDistinctReporters": 0,
      "rejectedReports": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "spi": {
      "settlements": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    }
  },
  "ownerStatistics": {
    "entries": {
      "registeredAccounts": 0,
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "fraudMarkers": {
      "applicationFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "distinctFraudReporters": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "muleAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "otherFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "scammerAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "totalFraudTransactionAmount": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "unknownFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "infractionReports": {
      "openReports": 0,
      "openReportsDistinctReporters": 0,
      "rejectedReports": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "spi": {
      "settlements": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    }
  },
  "responseTime": 0
}

Atualizar vínculo​

Endpoint para atualizar um vínculo.

A ser utilizado no cenário de atualização da informação da conta, nome e nome fantasia de um cliente, permanecendo este no mesmo PSP.

Somente podem ser atualizadas as informações de conta do vínculo, nome e nome fantasia do cliente. Outras atualizações do vínculo devem ser feitas por exclusão/inclusão do vínculo, portabilidade ou reivindicação de posse, a depender da situação.

Restrições

As seguintes restrições devem ser obedecidas na atualização de vínculo, de acordo com o tipo de chave:

  • Chaves EVP (aleatórias) - É permitida a alteração com o motivo BRANCH_TRANSFER.
  • Demais chaves - É permitida a alteração com os motivos USER_REQUESTED ou BRANCH_TRANSFER.

Atualiza as informações de uma chave (a chave continua vinculada ao mesmo PSP, mas as informações podem ser atualizadas).

Restrições do motivo:
  • Chaves EVP (aleatórias) - É permitida a alteração, porém, apenas com o motivo TRANSFERENCIA_AGENCIA.
  • Demais chaves - É permitida a alteração com os motivos SOLICITACAO_USUARIO ou TRANSFERENCIA_AGENCIA.
PUT /dict/entries/:key
Requer autorização para o escopo: keys.ind.write


Requisição

{
  "account": {
    "accountNumber": "0007654321",
    "accountType": "cacc",
    "branch": "0001",
    "openingDate": "2010-01-10t03:00:00Z",
    "participant": "12345678"
  },
  "key": "+5561988887777",
  "owner": {
    "name": "joão silva",
    "taxIdNumber": "11122233300",
    "type": "natural_person"
  },
  "reason": "user_requested"
}

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "account": {
      "accountnumber": "0007654321",
      "accounttype": "cacc",
      "branch": "0001",
      "openingdate": "2010-01-10t03:00:00.000z",
      "participant": "12345678"
    },
    "creationdate": "2019-11-18t03:00:00.000z",
    "key": "11122233300",
    "keyownershipdate": "2019-11-18t03:00:00.000z",
    "keytype": "cpf",
    "owner": {
      "name": "joão silva",
      "taxidnumber": "11122233300",
      "type": "natural_person"
    }
  },
  "responseTime": 0
}

Remover vínculo​

Endpoint para remover um vínculo de chave com conta.

POST /dict/entries/:key/delete
Requer autorização para o escopo: keys.ind.remove


Requisição

{
  "reason": "user_requested"
}

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "key": "+5561988887777"
}

Última atualização em