API do Serviço DICT

API Endpoint
https://api.dictra.com.br

O Serviço DICT fornece gerenciamento abrangente do diretório de chaves PIX em conformidade com a API DICT BACEN v2.10.0. Isso inclui:

  • DICT Core: Registro, consulta, exclusão de chaves PIX e reivindicações (portabilidade/posse)

  • MED 2.0: Recuperação de fraudes com rastreamento de transações, relatórios de infração e estornos automatizados

  • Limitação de Taxa: Limitação de taxa por token bucket conforme Manual BACEN v8.0 com categorias de instituições A-H

  • Recursos v2.10.0: Validação de chaves em lote, operações de arquivo CID e estatísticas antifraude

Autenticação

Todos os endpoints requerem:

  • Cabeçalho X-Participant-ISPB: Código ISPB de 8 dígitos do participante

  • Cabeçalho Authorization: Token JWT Bearer (em breve)

Limitação de Taxa

O serviço implementa limitação de taxa compatível com BACEN com buckets de token duplos:

Bucket do Usuário (PI-PayerId)

  • Tamanho do bucket varia por tipo de pagador

  • Reabastece 1 token/minuto

  • Penalidade 404: 20 tokens

Bucket do Participante (ISPB)

  • Tamanho do bucket varia por categoria da instituição (A-H)

  • Reabastecimento varia por categoria (2-25.000 tokens/min)

  • Penalidade 404: 3 tokens

Categorias de Instituições

Categoria Capacidade Reabast./min Exemplos
A 50.000 25.000 Banco do Brasil, Itaú, Santander
B 25.000 12.500 BTG Pactual, Nubank, Inter
C 10.000 5.000 Banrisul, JP Morgan
D 5.000 2.500 BRB, C6 Bank
E 2.000 1.000 PagSeguro, Mercado Pago
F 500 250 Pagar.me, Digio
G 200 100 Ame Digital
H 50 2 Instituições pequenas

Cabeçalhos

Cabeçalhos de Requisição

  • X-Participant-ISPB (obrigatório): ISPB do participante

  • PI-PayerId (obrigatório para consultas): Identificador único do pagador

  • PI-PayerType (opcional): NATURAL_PERSON ou LEGAL_PERSON

  • Content-Type: application/json

Cabeçalhos de Resposta

  • X-RateLimit-Limit: Capacidade total do bucket

  • X-RateLimit-Remaining: Tokens restantes

  • X-RateLimit-Reset: Timestamp Unix quando o bucket reabastece

  • PI-EndToEndId: EndToEndId gerado para correlação SPI (em consultas)

Códigos de Erro

Códigos de Status HTTP

  • 200 OK: Requisição bem-sucedida

  • 201 Created: Recurso criado com sucesso

  • 204 No Content: Exclusão bem-sucedida

  • 400 Bad Request: Parâmetros de requisição inválidos

  • 404 Not Found: Recurso não encontrado

  • 409 Conflict: Recurso já existe

  • 429 Too Many Requests: Limite de taxa excedido

  • 500 Internal Server Error: Erro do servidor

Códigos de Erro DICT

  • NOT_FOUND: Chave ou recurso não encontrado

  • KEY_EXISTS: Chave já registrada

  • INVALID_KEY_TYPE: Tipo de chave inválido

  • INVALID_OWNERSHIP: Validação de posse falhou

  • CLAIM_EXISTS: Reivindicação ativa já existe

  • INVALID_DELETE_REASON: Motivo de exclusão inválido para chaves EVP

  • KEY_LIMIT_EXCEEDED: Limite de chaves do participante excedido (5 para PF, 20 para PJ)

Grupo Health

Resource Group

Verificação de Saúde

GET https://api.dictra.com.br/health
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "healthy",
  "service": "dict-service"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Status do serviço"
    },
    "service": {
      "type": "string",
      "description": "Nome do serviço"
    }
  }
}

Obter Status de Saúde
GET/health

Sonda de vivacidade. Retorna o status de saúde do serviço.

Verificação de Prontidão

GET https://api.dictra.com.br/ready
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "ready",
  "service": "dict-service"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Prontidão do serviço"
    },
    "service": {
      "type": "string",
      "description": "Nome do serviço"
    }
  }
}

Obter Status de Prontidão
GET/ready

Sonda de prontidão. Inclui verificação de conectividade do banco de dados.

Entrada

POST https://api.dictra.com.br/api/v2/entries
Requestsexample 1
Headers
Content-Type: application/json
X-Participant-ISPB: 12345678
Body
{
  "keyType": "CPF",
  "key": "12345678901",
  "ownerType": "NATURAL_PERSON",
  "ownerTaxId": "12345678901",
  "ownerName": "João Silva",
  "tradeName": "Silva LTDA",
  "branch": "0001",
  "accountNumber": "123456",
  "accountType": "CACC",
  "openingDate": "2024-01-15"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "keyType": {
      "type": "string",
      "description": "Tipo de chave: CPF, CNPJ, PHONE, EMAIL, EVP"
    },
    "key": {
      "type": "string",
      "description": "Valor da chave (opcional para EVP)"
    },
    "ownerType": {
      "type": "string",
      "description": "NATURAL_PERSON ou LEGAL_PERSON"
    },
    "ownerTaxId": {
      "type": "string",
      "description": "CPF ou CNPJ"
    },
    "ownerName": {
      "type": "string",
      "description": "Nome completo do titular"
    },
    "tradeName": {
      "type": "string",
      "description": "Nome fantasia (somente PJ)"
    },
    "branch": {
      "type": "string",
      "description": "Código da agência de 4 dígitos"
    },
    "accountNumber": {
      "type": "string",
      "description": "Número da conta"
    },
    "accountType": {
      "type": "string",
      "description": "CACC, SLRY, SVGS, TRAN"
    },
    "openingDate": {
      "type": "string",
      "description": "Data de abertura da conta (AAAA-MM-DD)"
    }
  },
  "required": [
    "keyType",
    "ownerType",
    "ownerTaxId",
    "ownerName",
    "branch",
    "accountNumber",
    "accountType"
  ]
}
Responses201400409
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "keyType": "CPF",
  "key": "12345678901",
  "cid": "E1234567890123456789012345678901",
  "ownerType": "F",
  "ownerTaxId": "12345678901",
  "ownerName": "João Silva",
  "participantIspb": "12345678",
  "branch": "0001",
  "accountNumber": "123456",
  "accountType": "CACC",
  "status": "ACTIVE",
  "ownershipDate": "2024-01-15T10:30:00Z",
  "ownershipConfirmed": true,
  "createdAt": "2024-01-15T10:30:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "ID da entrada"
    },
    "keyType": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "cid": {
      "type": "string",
      "description": "ID de correlação DICT"
    },
    "ownerType": {
      "type": "string",
      "description": "F=Pessoa Física, J=Pessoa Jurídica"
    },
    "ownerTaxId": {
      "type": "string"
    },
    "ownerName": {
      "type": "string"
    },
    "participantIspb": {
      "type": "string"
    },
    "branch": {
      "type": "string"
    },
    "accountNumber": {
      "type": "string"
    },
    "accountType": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "ownershipDate": {
      "type": "string"
    },
    "ownershipConfirmed": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "Tipo de chave inválido"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "KEY_EXISTS",
  "error": "Chave já registrada"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Criar Chave PIX
POST/api/v2/entries

Criar uma nova entrada de chave PIX. Chaves EVP são geradas automaticamente se não fornecidas.

Limites de Chaves:

  • Pessoa Física (PF): 5 chaves por participante

  • Pessoa Jurídica (PJ): 20 chaves por participante

Validação de Agência: Deve ter exatamente 4 dígitos

Entrada por Chave

GET https://api.dictra.com.br/api/v2/entries/12345678901?keyType=CPF
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
PI-PayerId: usuario@exemplo.com
PI-PayerType: NATURAL_PERSON
Responses200404429
Headers
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1706270400
PI-EndToEndId: E12345678202401151030ABC123456789
Body
{
  "id": 1,
  "keyType": "CPF",
  "key": "12345678901",
  "cid": "E1234567890123456789012345678901",
  "ownerType": "F",
  "ownerTaxId": "12345678901",
  "ownerName": "João Silva",
  "participantIspb": "12345678",
  "branch": "0001",
  "accountNumber": "123456",
  "accountType": "CACC",
  "status": "ACTIVE",
  "ownershipDate": "2024-01-15T10:30:00Z",
  "ownershipConfirmed": true,
  "createdAt": "2024-01-15T10:30:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "keyType": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "cid": {
      "type": "string"
    },
    "ownerType": {
      "type": "string"
    },
    "ownerTaxId": {
      "type": "string"
    },
    "ownerName": {
      "type": "string"
    },
    "participantIspb": {
      "type": "string"
    },
    "branch": {
      "type": "string"
    },
    "accountNumber": {
      "type": "string"
    },
    "accountType": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "ownershipDate": {
      "type": "string"
    },
    "ownershipConfirmed": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "NOT_FOUND",
  "error": "chave não encontrada"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "Limite de taxa excedido",
  "bucket": "user",
  "remaining": 0,
  "retry_after": 60
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "bucket": {
      "type": "string",
      "description": "Qual bucket atingiu o limite"
    },
    "remaining": {
      "type": "number"
    },
    "retry_after": {
      "type": "number",
      "description": "Segundos para aguardar"
    }
  }
}

Obter Chave PIX
GET/api/v2/entries/{key}?keyType={keyType}

Consultar uma chave PIX. Implementa limitação de taxa compatível com BACEN com buckets de token.

Fluxo de Limitação de Taxa:

  1. Valida cabeçalho PI-PayerId
  2. Verifica cache de existência (30 dias para encontrado, 5 min para 404)
  3. Verifica buckets de token do usuário + participante
  4. Gera EndToEndId para correlação SPI
  5. Processa consulta e registra métricas
  6. Retorna cabeçalhos de limite de taxa

Consumo de Tokens:

  • Encontrado (NATURAL_PERSON): 1 token

  • Encontrado (LEGAL_PERSON): 2 tokens

  • Penalidade não encontrado: 20 tokens (usuário), 3 tokens (participante)

URI Parameters
HideShow
key
string (required) Example: 12345678901

Valor da chave PIX

keyType
string (required) Example: CPF

Tipo de chave

DELETE https://api.dictra.com.br/api/v2/entries/12345678901?keyType=CPF
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses204400404
This response has no content.
Headers
Content-Type: application/json
Body
{
  "code": "INVALID_DELETE_REASON",
  "error": "Chaves EVP só podem ser excluídas com BRANCH_TRANSFER, RECONCILIATION ou RFB_VALIDATION"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "NOT_FOUND",
  "error": "chave não encontrada"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Excluir Chave PIX
DELETE/api/v2/entries/{key}?keyType={keyType}

Excluir uma entrada de chave PIX.

Restrições EVP (v2.10.0): Chaves EVP só podem ser excluídas com motivos:

  • BRANCH_TRANSFER

  • RECONCILIATION

  • RFB_VALIDATION

URI Parameters
HideShow
key
string (required) Example: 12345678901

Valor da chave PIX

keyType
string (required) Example: CPF

Tipo de chave

reason
string (optional) Example: USER_REQUESTED

Motivo da exclusão

Entrada por CID

GET https://api.dictra.com.br/api/v2/entries/cid/E1234567890123456789012345678901
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200404
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "keyType": "CPF",
  "key": "12345678901",
  "cid": "E1234567890123456789012345678901",
  "ownerType": "F",
  "ownerTaxId": "12345678901",
  "ownerName": "João Silva",
  "participantIspb": "12345678",
  "branch": "0001",
  "accountNumber": "123456",
  "accountType": "CACC",
  "status": "ACTIVE",
  "ownershipDate": "2024-01-15T10:30:00Z",
  "ownershipConfirmed": true,
  "createdAt": "2024-01-15T10:30:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "keyType": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "cid": {
      "type": "string"
    },
    "ownerType": {
      "type": "string"
    },
    "ownerTaxId": {
      "type": "string"
    },
    "ownerName": {
      "type": "string"
    },
    "participantIspb": {
      "type": "string"
    },
    "branch": {
      "type": "string"
    },
    "accountNumber": {
      "type": "string"
    },
    "accountType": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "ownershipDate": {
      "type": "string"
    },
    "ownershipConfirmed": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "NOT_FOUND",
  "error": "chave não encontrada"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Obter Entrada por CID
GET/api/v2/entries/cid/{cid}

Recuperar uma entrada de chave PIX por seu ID de correlação DICT (CID).

URI Parameters
HideShow
cid
string (required) Example: E1234567890123456789012345678901

ID de correlação DICT

Reivindicações para Chave

POST https://api.dictra.com.br/api/v2/entries/12345678901/claims
Requestsexample 1
Headers
Content-Type: application/json
X-Participant-ISPB: 87654321
Body
{
  "keyType": "CPF",
  "claimerTaxId": "12345678901",
  "claimerAccount": "654321",
  "claimerBranch": "0002",
  "claimerAccountType": "CACC",
  "claimerName": "João Silva",
  "claimerOwnerType": "NATURAL_PERSON"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "keyType": {
      "type": "string"
    },
    "claimerTaxId": {
      "type": "string"
    },
    "claimerAccount": {
      "type": "string"
    },
    "claimerBranch": {
      "type": "string"
    },
    "claimerAccountType": {
      "type": "string"
    },
    "claimerName": {
      "type": "string"
    },
    "claimerOwnerType": {
      "type": "string"
    }
  },
  "required": [
    "keyType",
    "claimerTaxId",
    "claimerAccount",
    "claimerBranch",
    "claimerAccountType",
    "claimerName",
    "claimerOwnerType"
  ]
}
Responses201409
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "claimId": "C1234567890",
  "type": "PORTABILITY",
  "status": "OPEN",
  "keyType": "CPF",
  "keyValue": "12345678901",
  "donorIspb": "12345678",
  "donorTaxId": "12345678901",
  "donorAccount": "123456",
  "claimerIspb": "87654321",
  "claimerTaxId": "12345678901",
  "claimerAccount": "654321",
  "donorDeadline": "2024-01-29T10:30:00Z",
  "claimerDeadline": "2024-02-14T10:30:00Z",
  "autoResolved": false,
  "createdAt": "2024-01-15T10:30:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "claimId": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "keyType": {
      "type": "string"
    },
    "keyValue": {
      "type": "string"
    },
    "donorIspb": {
      "type": "string"
    },
    "donorTaxId": {
      "type": "string"
    },
    "donorAccount": {
      "type": "string"
    },
    "claimerIspb": {
      "type": "string"
    },
    "claimerTaxId": {
      "type": "string"
    },
    "claimerAccount": {
      "type": "string"
    },
    "donorDeadline": {
      "type": "string",
      "description": "D+14"
    },
    "claimerDeadline": {
      "type": "string",
      "description": "D+30"
    },
    "autoResolved": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "CLAIM_EXISTS",
  "error": "Reivindicação ativa já existe para esta chave"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Criar Reivindicação
POST/api/v2/entries/{key}/claims

Criar uma reivindicação de portabilidade ou posse para uma chave PIX.

Tipos de Reivindicação:

  • PORTABILITY: Mesmo titular (CPF/CNPJ), PSP diferente

  • OWNERSHIP: Titular diferente

Prazos (D0 = criação da reivindicação):

  • D+7: Notificação da janela 1 do doador

  • D+14: Prazo do doador (auto-confirma se sem resposta)

  • D+30: Prazo do reivindicante (auto-cancela se não concluído)

URI Parameters
HideShow
key
string (required) Example: 12345678901

Valor da chave PIX

keyType
string (required) Example: CPF

Parâmetro de consulta

GET https://api.dictra.com.br/api/v2/entries/12345678901/claims
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200
Headers
Content-Type: application/json
Body
{
  "claims": [
    {
      "id": 1,
      "claimId": "C1234567890",
      "type": "PORTABILITY",
      "status": "OPEN",
      "keyType": "CPF",
      "keyValue": "12345678901",
      "donorIspb": "12345678",
      "donorTaxId": "12345678901",
      "claimerIspb": "87654321",
      "claimerTaxId": "12345678901",
      "donorDeadline": "2024-01-29T10:30:00Z",
      "claimerDeadline": "2024-02-14T10:30:00Z",
      "autoResolved": false,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "claims": {
      "type": "array"
    }
  }
}

Listar Reivindicações para Chave
GET/api/v2/entries/{key}/claims

Listar todas as reivindicações para uma chave PIX específica.

URI Parameters
HideShow
key
string (required) Example: 12345678901

Valor da chave PIX

keyType
string (required) Example: CPF

Parâmetro de consulta

Atualização de Reivindicação

PATCH https://api.dictra.com.br/api/v2/entries/12345678901/claims/C1234567890
Requestsexample 1
Headers
Content-Type: application/json
X-Participant-ISPB: 12345678
Body
{
  "action": "CONFIRM",
  "reason": "Doador aprovou transferência"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "CONFIRM, CANCEL ou COMPLETE"
    },
    "reason": {
      "type": "string"
    }
  },
  "required": [
    "action"
  ]
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "claimId": "C1234567890",
  "type": "PORTABILITY",
  "status": "CONFIRMED",
  "keyType": "CPF",
  "keyValue": "12345678901",
  "donorIspb": "12345678",
  "claimerIspb": "87654321",
  "donorDeadline": "2024-01-29T10:30:00Z",
  "claimerDeadline": "2024-02-14T10:30:00Z",
  "confirmReason": "DONOR_CONFIRMED",
  "autoResolved": false,
  "createdAt": "2024-01-15T10:30:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "claimId": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "keyType": {
      "type": "string"
    },
    "keyValue": {
      "type": "string"
    },
    "donorIspb": {
      "type": "string"
    },
    "claimerIspb": {
      "type": "string"
    },
    "donorDeadline": {
      "type": "string"
    },
    "claimerDeadline": {
      "type": "string"
    },
    "confirmReason": {
      "type": "string"
    },
    "autoResolved": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "Ação inválida. Deve ser CONFIRM, CANCEL ou COMPLETE"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Atualizar Reivindicação
PATCH/api/v2/entries/{key}/claims/{claimId}

Atualizar status da reivindicação (CONFIRM, CANCEL, COMPLETE).

Ações:

  • CONFIRM: Doador confirma transferência (ou sistema auto-confirma em D+14)

  • CANCEL: Qualquer parte cancela

  • COMPLETE: Reivindicante conclui validação de posse

Rastreamento v2.10.0:

  • confirmReason: DONOR_CONFIRMED, DONOR_TIMEOUT, AUTOMATIC

  • cancelledBy: DONOR, CLAIMER, SYSTEM

URI Parameters
HideShow
key
string (required) Example: 12345678901

Valor da chave PIX

claimId
string (required) Example: C1234567890

ID da reivindicação

Lista de Reivindicações

GET https://api.dictra.com.br/api/v2/claims?role=as_claimer&status=OPEN&page=1&pageSize=20
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200
Headers
Content-Type: application/json
Body
{
  "claims": [
    {
      "id": 1,
      "claimId": "C1234567890",
      "type": "PORTABILITY",
      "status": "OPEN",
      "keyType": "CPF",
      "keyValue": "12345678901",
      "donorIspb": "12345678",
      "claimerIspb": "87654321",
      "donorDeadline": "2024-01-29T10:30:00Z",
      "claimerDeadline": "2024-02-14T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "claims": {
      "type": "array"
    },
    "totalCount": {
      "type": "number"
    },
    "page": {
      "type": "number"
    },
    "pageSize": {
      "type": "number"
    }
  }
}

Listar Todas as Reivindicações
GET/api/v2/claims?role={role}&status={status}&page={page}&pageSize={pageSize}

Listar reivindicações para o participante (como doador ou reivindicante).

URI Parameters
HideShow
role
string (optional) Example: as_claimer

as_donor ou as_claimer

status
string (optional) Example: OPEN

Filtrar por status

page
number (optional) Example: 1

Número da página

pageSize
number (optional) Example: 20

Itens por página (máx 100)

Reivindicação por ID

GET https://api.dictra.com.br/api/v2/claims/C1234567890
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200404
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "claimId": "C1234567890",
  "type": "PORTABILITY",
  "status": "OPEN",
  "keyType": "CPF",
  "keyValue": "12345678901",
  "donorIspb": "12345678",
  "donorTaxId": "12345678901",
  "claimerIspb": "87654321",
  "claimerTaxId": "12345678901",
  "donorDeadline": "2024-01-29T10:30:00Z",
  "claimerDeadline": "2024-02-14T10:30:00Z",
  "autoResolved": false,
  "createdAt": "2024-01-15T10:30:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "claimId": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "keyType": {
      "type": "string"
    },
    "keyValue": {
      "type": "string"
    },
    "donorIspb": {
      "type": "string"
    },
    "donorTaxId": {
      "type": "string"
    },
    "claimerIspb": {
      "type": "string"
    },
    "claimerTaxId": {
      "type": "string"
    },
    "donorDeadline": {
      "type": "string"
    },
    "claimerDeadline": {
      "type": "string"
    },
    "autoResolved": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "NOT_FOUND",
  "error": "reivindicação não encontrada"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Obter Reivindicação
GET/api/v2/claims/{claimId}

Recuperar uma reivindicação por ID.

URI Parameters
HideShow
claimId
string (required) Example: C1234567890

ID da reivindicação

Recuperações de Fundos

POST https://api.dictra.com.br/api/v2/funds-recoveries
Requestsexample 1
Headers
Content-Type: application/json
X-Participant-ISPB: 12345678
Body
{
  "creator_ispb": "12345678",
  "root_transaction_id": "E12345678202401151030ABC12345",
  "fraud_type: `SCAM` (string, required) - FRAUDULENT_ACCESS, SCAM, ACCOUNT_TAKEOVER, OTHER": "Hello, world!",
  "report_details": "Cliente relatou transferência não autorizada",
  "min_transaction_amount": 100,
  "max_transactions": 500,
  "hop_window": "P1D",
  "max_hops": 5
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "creator_ispb": {
      "type": "string",
      "description": "ISPB do banco da vítima (8 caracteres)"
    },
    "root_transaction_id": {
      "type": "string",
      "description": "EndToEndId da transação raiz (32 caracteres)"
    },
    "fraud_type: `SCAM` (string, required) - FRAUDULENT_ACCESS, SCAM, ACCOUNT_TAKEOVER, OTHER": {
      "type": "string"
    },
    "report_details": {
      "type": "string"
    },
    "min_transaction_amount": {
      "type": "number",
      "description": "Valor mínimo para rastrear (padrão: 100,00)"
    },
    "max_transactions": {
      "type": "number",
      "description": "Máximo de transações no grafo (padrão: 500)"
    },
    "hop_window": {
      "type": "string",
      "description": "Duração ISO 8601 (padrão: 24h)"
    },
    "max_hops": {
      "type": "number",
      "description": "Profundidade máxima de saltos (padrão: 5)"
    }
  },
  "required": [
    "creator_ispb",
    "root_transaction_id"
  ]
}
Responses201409
Headers
Content-Type: application/json
Body
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "creator_ispb": "12345678",
  "root_transaction_id": "E12345678202401151030ABC12345",
  "status": "CREATED",
  "fraud_type": "SCAM",
  "min_transaction_amount": 100,
  "max_transactions": 500,
  "hop_window": "24h0m0s",
  "max_hops": 5,
  "created_at": "2024-01-15T10:30:00Z",
  "last_updated": "2024-01-15T10:30:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "creator_ispb": {
      "type": "string"
    },
    "root_transaction_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "fraud_type": {
      "type": "string"
    },
    "min_transaction_amount": {
      "type": "number"
    },
    "max_transactions": {
      "type": "number"
    },
    "hop_window": {
      "type": "string"
    },
    "max_hops": {
      "type": "number"
    },
    "created_at": {
      "type": "string"
    },
    "last_updated": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "FR001",
  "error": "recuperação de fundos já existe para esta transação"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Criar Recuperação de Fundos
POST/api/v2/funds-recoveries

Iniciar um processo de recuperação de fraudes MED 2.0 para uma transação fraudulenta.

Estados do Fluxo de Trabalho:

  1. CREATED → Estado inicial
  2. TRACKED → Grafo de rastreamento gerado
  3. AWAITING_ANALYSIS → Pronto para revisão manual
  4. ANALYSED → Análise concluída
  5. REFUNDING → Processo de estorno iniciado
  6. COMPLETED → Todos os estornos processados
  7. CANCELLED → Processo cancelado

Parâmetros do Grafo de Rastreamento:

  • MinTransactionAmount: R$ 100,00 (padrão)

  • MaxTransactions: 500 (padrão)

  • HopWindow: 24 horas (padrão)

  • MaxHops: 5 (padrão)

GET https://api.dictra.com.br/api/v2/funds-recoveries
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "creator_ispb": "12345678",
      "root_transaction_id": "E12345678202401151030ABC12345",
      "status": "TRACKED",
      "fraud_type": "SCAM",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total_count": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "page": {
      "type": "number"
    },
    "page_size": {
      "type": "number"
    },
    "total_count": {
      "type": "number"
    }
  }
}

Listar Recuperações de Fundos
GET/api/v2/funds-recoveries

Listar recuperações de fundos com filtros opcionais.

URI Parameters
HideShow
creator_ispb
string (optional) Example: 12345678

Filtrar por criador

status
string (optional) Example: CREATED

Filtrar por status

start_date
string (optional) Example: 2024-01-01T00:00:00Z

ISO 8601

end_date
string (optional) Example: 2024-01-31T23:59:59Z

ISO 8601

page
number (optional) Example: 1

Número da página (padrão: 1)

page_size
number (optional) Example: 20

Itens por página (máx 100, padrão: 20)

Recuperação de Fundos

GET https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200404
Headers
Content-Type: application/json
Body
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "creator_ispb": "12345678",
  "root_transaction_id": "E12345678202401151030ABC12345",
  "status": "TRACKED",
  "fraud_type": "SCAM",
  "min_transaction_amount": 100,
  "max_transactions": 500,
  "hop_window": "24h0m0s",
  "max_hops": 5,
  "created_at": "2024-01-15T10:30:00Z",
  "tracked_at": "2024-01-15T10:35:00Z",
  "last_updated": "2024-01-15T10:35:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "creator_ispb": {
      "type": "string"
    },
    "root_transaction_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "fraud_type": {
      "type": "string"
    },
    "min_transaction_amount": {
      "type": "number"
    },
    "max_transactions": {
      "type": "number"
    },
    "hop_window": {
      "type": "string"
    },
    "max_hops": {
      "type": "number"
    },
    "created_at": {
      "type": "string"
    },
    "tracked_at": {
      "type": "string"
    },
    "last_updated": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "recuperação de fundos não encontrada"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Obter Recuperação de Fundos
GET/api/v2/funds-recoveries/{id}

Recuperar uma recuperação de fundos por ID.

URI Parameters
HideShow
id
string (required) Example: 550e8400-e29b-41d4-a716-446655440000

UUID da recuperação de fundos

details
boolean (optional) Example: true

Incluir grafo de rastreamento, relatórios de infração e estornos

Verificar Chaves

POST https://api.dictra.com.br/api/v2/keys/check
Requestsexample 1
Headers
Content-Type: application/json
X-Participant-ISPB: 12345678
Body
{
  "keys": [
    "12345678901",
    "teste@exemplo.com",
    "+5511999999999"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "keys": {
      "type": "array",
      "description": "1-200 chaves"
    }
  },
  "required": [
    "keys"
  ]
}
Responses200400429
Headers
Content-Type: application/json
Body
{
  "keys": [
    {
      "key": "12345678901",
      "hasEntry": true
    },
    {
      "key": "teste@exemplo.com",
      "hasEntry": false
    },
    {
      "key": "+5511999999999",
      "hasEntry": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "keys": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "INVALID_REQUEST",
  "error": "Array de chaves deve conter 1-200 elementos"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "Limite de taxa excedido. 70 requisições/min permitidas"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Validar Chaves em Lote
POST/api/v2/keys/check

Verificar se múltiplas chaves existem no DICT (1-200 chaves por requisição).

Limite de Taxa: 70 requisições/min por participante

Conformidade BACEN v2.10.0: Retorna apenas hasEntry booleano (sem dados do titular)

Arquivos CID

POST https://api.dictra.com.br/api/v2/cids/files
Requestsexample 1
Headers
Content-Type: application/json
X-Participant-ISPB: 12345678
Body
{
  "requestId": "REQ20240115001"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Chave de idempotência"
    }
  },
  "required": [
    "requestId"
  ]
}
Responses201409429
Headers
Content-Type: application/json
Body
{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "requestId": "REQ20240115001",
  "participantIspb": "12345678",
  "status": "PENDING",
  "entryCount": 0,
  "createdAt": "2024-01-15T10:00:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "participantIspb": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "description": "PENDING, PROCESSING, COMPLETED, FAILED"
    },
    "entryCount": {
      "type": "number"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "CONFLICT",
  "error": "Requisição de arquivo com este requestId já existe"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "Limite diário excedido. 40 arquivos CID permitidos por dia"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Criar Arquivo CID
POST/api/v2/cids/files

Solicitar um arquivo CID em lote para reconciliação (limite de 40 arquivos/dia por participante).

Geração de Arquivo:

  • Inclui todas as chaves do participante com CIDs

  • Disponível por 30 dias

  • Contém: keyType, key, CID, ownerTaxId, participantIspb

Limite de Taxa: 40/dia por participante

Arquivo CID

GET https://api.dictra.com.br/api/v2/cids/files/990e8400-e29b-41d4-a716-446655440004
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200403
Headers
Content-Type: application/json
Body
{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "requestId": "REQ20240115001",
  "participantIspb": "12345678",
  "status": "COMPLETED",
  "fileUrl": "https://storage.dictra.com.br/cid-files/990e8400...",
  "entryCount": 1250,
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:05:00Z",
  "expiresAt": "2024-02-14T10:05:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "participantIspb": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "fileUrl": {
      "type": "string"
    },
    "entryCount": {
      "type": "number"
    },
    "createdAt": {
      "type": "string"
    },
    "completedAt": {
      "type": "string"
    },
    "expiresAt": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "FORBIDDEN",
  "error": "Acesso negado a este arquivo CID"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Obter Arquivo CID
GET/api/v2/cids/files/{fileId}

Recuperar status e URL de download do arquivo CID.

URI Parameters
HideShow
fileId
string (required) Example: 990e8400-e29b-41d4-a716-446655440004

UUID do arquivo CID

Estatísticas de Pessoa

GET https://api.dictra.com.br/api/v2/entries/statistics/person?taxId=12345678901
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200400404
Headers
Content-Type: application/json
Body
{
  "personTaxId": "12345678901",
  "taxIdType": "CPF",
  "spiMetrics": {
    "settlementsD90": 150,
    "settlementsM12": 500,
    "settlementsM60": 2000
  },
  "fraudMarkers": {
    "applicationFrauds": 0,
    "muleAccounts": 1,
    "scammerAccounts": 0,
    "otherFrauds": 0,
    "totalAmount": 5000,
    "distinctReporters": 2
  },
  "infractionReports": {
    "openReports": 1,
    "distinctReporters": 2,
    "rejectedReports": 0
  },
  "entryCount": 3,
  "watermark": "2024-01-15T10:00:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "personTaxId": {
      "type": "string"
    },
    "taxIdType": {
      "type": "string",
      "description": "CPF ou CNPJ"
    },
    "spiMetrics": {
      "type": "object",
      "properties": {
        "settlementsD90": {
          "type": "number"
        },
        "settlementsM12": {
          "type": "number"
        },
        "settlementsM60": {
          "type": "number"
        }
      }
    },
    "fraudMarkers": {
      "type": "object",
      "properties": {
        "applicationFrauds": {
          "type": "number"
        },
        "muleAccounts": {
          "type": "number"
        },
        "scammerAccounts": {
          "type": "number"
        },
        "otherFrauds": {
          "type": "number"
        },
        "totalAmount": {
          "type": "number"
        },
        "distinctReporters": {
          "type": "number"
        }
      }
    },
    "infractionReports": {
      "type": "object",
      "properties": {
        "openReports": {
          "type": "number"
        },
        "distinctReporters": {
          "type": "number"
        },
        "rejectedReports": {
          "type": "number"
        }
      }
    },
    "entryCount": {
      "type": "number"
    },
    "watermark": {
      "type": "string",
      "description": "Timestamp do cache"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "Formato de taxId inválido. Deve ter 11 dígitos (CPF) ou 14 dígitos (CNPJ)"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "NOT_FOUND",
  "error": "estatísticas não encontradas para taxId"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Obter Estatísticas de Pessoa
GET/api/v2/entries/statistics/person?taxId={taxId}

Obter estatísticas antifraude agregadas para uma pessoa (por CPF/CNPJ).

Estatísticas Incluem:

  • Métricas SPI: Contagens de liquidação (D+90, M+12, M+60)

  • Marcadores de Fraude: Fraudes de aplicação, contas laranjas, contas de golpistas, valor total de fraude

  • Relatórios de Infração: Relatórios abertos/rejeitados, denunciantes distintos

  • Entradas: Total de contas registradas

Limite de Taxa: 12.000 requisições/min por participante

URI Parameters
HideShow
taxId
string (required) Example: 12345678901

CPF (11 dígitos) ou CNPJ (14 dígitos)

Estatísticas de Chave

GET https://api.dictra.com.br/api/v2/entries/statistics/key?keyType=EMAIL&key=teste@exemplo.com
Requestsexample 1
Headers
X-Participant-ISPB: 12345678
Responses200400404
Headers
Content-Type: application/json
Body
{
  "keyType": "EMAIL",
  "keyValue": "teste@exemplo.com",
  "spiMetrics": {
    "settlementsD90": 50,
    "settlementsM12": 180,
    "settlementsM60": 700
  },
  "fraudMarkers": {
    "applicationFrauds": 0,
    "distinctReporters": 0
  },
  "infractionReports": {
    "openReports": 0,
    "distinctReporters": 0,
    "rejectedReports": 0
  },
  "entries": {
    "distinctAccounts": 1
  },
  "watermark": "2024-01-15T10:00:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "keyType": {
      "type": "string"
    },
    "keyValue": {
      "type": "string"
    },
    "spiMetrics": {
      "type": "object",
      "properties": {
        "settlementsD90": {
          "type": "number"
        },
        "settlementsM12": {
          "type": "number"
        },
        "settlementsM60": {
          "type": "number"
        }
      }
    },
    "fraudMarkers": {
      "type": "object",
      "properties": {
        "applicationFrauds": {
          "type": "number"
        },
        "distinctReporters": {
          "type": "number"
        }
      }
    },
    "infractionReports": {
      "type": "object",
      "properties": {
        "openReports": {
          "type": "number"
        },
        "distinctReporters": {
          "type": "number"
        },
        "rejectedReports": {
          "type": "number"
        }
      }
    },
    "entries": {
      "type": "object",
      "properties": {
        "distinctAccounts": {
          "type": "number"
        }
      }
    },
    "watermark": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": "keyType inválido. Deve ser: EMAIL, PHONE, CPF, CNPJ, EVP"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "NOT_FOUND",
  "error": "estatísticas não encontradas para chave"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Obter Estatísticas de Chave
GET/api/v2/entries/statistics/key?keyType={keyType}&key={key}

Obter estatísticas antifraude agregadas para uma chave PIX.

Estatísticas Incluem:

  • Métricas SPI: Contagens de liquidação

  • Marcadores de Fraude: Fraudes de aplicação, denunciantes distintos

  • Relatórios de Infração: Relatórios abertos/rejeitados

  • Entradas: Contas distintas registradas com esta chave

Limite de Taxa: 12.000 requisições/min por participante

URI Parameters
HideShow
keyType
string (required) Example: EMAIL

EMAIL, PHONE, CPF, CNPJ, EVP

key
string (required) Example: teste@exemplo.com

Valor da chave

Generated by aglio on 24 Jan 2026