DICT Service API

API Endpoint

https://api.dictra.com.br

The DICT Service provides comprehensive PIX key directory management compliant with BACEN DICT API v2.10.0. This includes:

Core DICT: PIX key registration, lookup, deletion, and claims (portability/ownership)
MED 2.0: Fraud recovery with transaction tracing, infraction reports, and automated refunds
Rate Limiting: Token bucket rate limiting per BACEN Manual v8.0 with institution categories A-H
v2.10.0 Features: Batch key validation, CID file operations, and anti-fraud statistics

Authentication

All endpoints require:

X-Participant-ISPB header: 8-digit ISPB code of the participant
Authorization header: JWT Bearer token (coming soon)

Rate Limiting

The service implements BACEN-compliant rate limiting with dual token buckets:

User Bucket (PI-PayerId)

Bucket size varies by payer type
Refills 1 token/minute
404 penalty: 20 tokens

Participant Bucket (ISPB)

Bucket size varies by institution category (A-H)
Refills vary by category (2-25,000 tokens/min)
404 penalty: 3 tokens

Institution Categories

Category	Capacity	Refill/min	Examples
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	Small institutions

Headers

Request Headers

X-Participant-ISPB (required): Participant ISPB
PI-PayerId (required for queries): Unique payer identifier
PI-PayerType (optional): NATURAL_PERSON or LEGAL_PERSON
Content-Type: application/json

Response Headers

X-RateLimit-Limit: Total bucket capacity
X-RateLimit-Remaining: Remaining tokens
X-RateLimit-Reset: Unix timestamp when bucket refills
PI-EndToEndId: Generated EndToEndId for SPI correlation (on queries)

Error Codes

HTTP Status Codes

200 OK: Successful request
201 Created: Resource created successfully
204 No Content: Successful deletion
400 Bad Request: Invalid request parameters
404 Not Found: Resource not found
409 Conflict: Resource already exists
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

DICT Error Codes

NOT_FOUND: Key or resource not found
KEY_EXISTS: Key already registered
INVALID_KEY_TYPE: Invalid key type
INVALID_OWNERSHIP: Ownership validation failed
CLAIM_EXISTS: Active claim already exists
INVALID_DELETE_REASON: Invalid delete reason for EVP keys
KEY_LIMIT_EXCEEDED: Participant key limit exceeded (5 for PF, 20 for PJ)

Health ¶

Health Check ¶

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": "Service status"
    },
    "service": {
      "type": "string",
      "description": "Service name"
    }
  }
}

Get Health Status
GET`/health`

Liveness probe. Returns service health status.

Readiness Check ¶

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": "Service readiness"
    },
    "service": {
      "type": "string",
      "description": "Service name"
    }
  }
}

Get Readiness Status
GET`/ready`

Readiness probe. Includes database connectivity check.

Core DICT - PIX Keys ¶

Entry ¶

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": "Key type: CPF, CNPJ, PHONE, EMAIL, EVP"
    },
    "key": {
      "type": "string",
      "description": "Key value (optional for EVP)"
    },
    "ownerType": {
      "type": "string",
      "description": "NATURAL_PERSON or LEGAL_PERSON"
    },
    "ownerTaxId": {
      "type": "string",
      "description": "CPF or CNPJ"
    },
    "ownerName": {
      "type": "string",
      "description": "Owner full name"
    },
    "tradeName": {
      "type": "string",
      "description": "Trade name (PJ only)"
    },
    "branch": {
      "type": "string",
      "description": "4-digit branch code"
    },
    "accountNumber": {
      "type": "string",
      "description": "Account number"
    },
    "accountType": {
      "type": "string",
      "description": "CACC, SLRY, SVGS, TRAN"
    },
    "openingDate": {
      "type": "string",
      "description": "Account opening date (YYYY-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": "Entry ID"
    },
    "keyType": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "cid": {
      "type": "string",
      "description": "DICT correlation ID"
    },
    "ownerType": {
      "type": "string",
      "description": "F=Natural Person, J=Legal Person"
    },
    "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": "Invalid keyType"
}

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": "Key already registered"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Create PIX Key
POST`/api/v2/entries`

Create a new PIX key entry. EVP keys are auto-generated if not provided.

Key Limits:

Natural Person (PF): 5 keys per participant
Legal Person (PJ): 20 keys per participant

Branch Validation: Must be exactly 4 digits

Entry by Key ¶

GET https://api.dictra.com.br/api/v2/entries/12345678901?keyType=CPF

Requestsexample 1

Headers

X-Participant-ISPB: 12345678
PI-PayerId: user@example.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": "key not found"
}

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": "Rate limit exceeded",
  "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": "Which bucket triggered limit"
    },
    "remaining": {
      "type": "number"
    },
    "retry_after": {
      "type": "number",
      "description": "Seconds to wait"
    }
  }
}

Get PIX Key
GET`/api/v2/entries/{key}?keyType={keyType}`

Query a PIX key. Implements BACEN-compliant rate limiting with token buckets.

Rate Limiting Flow:

Validates PI-PayerId header
Checks existence cache (30 days for found, 5 min for 404)
Checks user + participant token buckets
Generates EndToEndId for SPI correlation
Processes lookup and records metrics
Returns rate limit headers

Token Consumption:

Found (NATURAL_PERSON): 1 token
Found (LEGAL_PERSON): 2 tokens
Not Found penalty: 20 tokens (user), 3 tokens (participant)

URI Parameters

HideShow

key: string (required) Example: 12345678901
PIX key value
keyType: string (required) Example: CPF
Key type

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": "EVP keys can only be deleted with BRANCH_TRANSFER, RECONCILIATION, or 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": "key not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Delete PIX Key
DELETE`/api/v2/entries/{key}?keyType={keyType}`

Delete a PIX key entry.

EVP Restrictions (v2.10.0): EVP keys can only be deleted with reasons:

BRANCH_TRANSFER
RECONCILIATION
RFB_VALIDATION

URI Parameters

HideShow

key: string (required) Example: 12345678901
PIX key value
keyType: string (required) Example: CPF
Key type
reason: string (optional) Example: USER_REQUESTED
Delete reason

Entry by 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": "key not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Get Entry by CID
GET`/api/v2/entries/cid/{cid}`

Retrieve a PIX key entry by its DICT correlation ID (CID).

URI Parameters

HideShow

cid: string (required) Example: E1234567890123456789012345678901
DICT correlation ID

Core DICT - Claims ¶

Claims for Key ¶

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": "Active claim already exists for this key"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Create Claim
POST`/api/v2/entries/{key}/claims`

Create a portability or ownership claim for a PIX key.

Claim Types:

PORTABILITY: Same owner (CPF/CNPJ), different PSP
OWNERSHIP: Different owner

Deadlines (D0 = claim creation):

D+7: Donor window 1 notification
D+14: Donor deadline (auto-confirm if no response)
D+30: Claimer deadline (auto-cancel if not completed)

URI Parameters

HideShow

key: string (required) Example: 12345678901
PIX key value
keyType: string (required) Example: CPF
Query parameter

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"
    }
  }
}

List Claims for Key
GET`/api/v2/entries/{key}/claims`

List all claims for a specific PIX key.

URI Parameters

HideShow

key: string (required) Example: 12345678901
PIX key value
keyType: string (required) Example: CPF
Query parameter

Claim Update ¶

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": "Donor approved transfer"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "CONFIRM, CANCEL, or 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": "Invalid action. Must be CONFIRM, CANCEL, or COMPLETE"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Update Claim
PATCH`/api/v2/entries/{key}/claims/{claimId}`

Update claim status (CONFIRM, CANCEL, COMPLETE).

Actions:

CONFIRM: Donor confirms transfer (or system auto-confirms at D+14)
CANCEL: Either party cancels
COMPLETE: Claimer completes ownership validation

v2.10.0 Tracking:

confirmReason: DONOR_CONFIRMED, DONOR_TIMEOUT, AUTOMATIC
cancelledBy: DONOR, CLAIMER, SYSTEM

URI Parameters

HideShow

key: string (required) Example: 12345678901
PIX key value
claimId: string (required) Example: C1234567890
Claim ID

Claims List ¶

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"
    }
  }
}

List All Claims
GET`/api/v2/claims?role={role}&status={status}&page={page}&pageSize={pageSize}`

List claims for the participant (as donor or claimer).

URI Parameters

HideShow

role: string (optional) Example: as_claimer
as_donor or as_claimer
status: string (optional) Example: OPEN
Filter by status
page: number (optional) Example: 1
Page number
pageSize: number (optional) Example: 20
Items per page (max 100)

Claim by 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": "claim not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Get Claim
GET`/api/v2/claims/{claimId}`

Retrieve a claim by ID.

URI Parameters

HideShow

claimId: string (required) Example: C1234567890
Claim ID

MED 2.0 - Fraud Recovery ¶

Funds Recoveries ¶

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": "Customer reported unauthorized transfer",
  "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": "Victim's bank ISPB (8 chars)"
    },
    "root_transaction_id": {
      "type": "string",
      "description": "Root transaction EndToEndId (32 chars)"
    },
    "fraud_type: `SCAM` (string, required) - FRAUDULENT_ACCESS, SCAM, ACCOUNT_TAKEOVER, OTHER": {
      "type": "string"
    },
    "report_details": {
      "type": "string"
    },
    "min_transaction_amount": {
      "type": "number",
      "description": "Minimum amount to trace (default: 100.00)"
    },
    "max_transactions": {
      "type": "number",
      "description": "Max transactions in graph (default: 500)"
    },
    "hop_window": {
      "type": "string",
      "description": "ISO 8601 duration (default: 24h)"
    },
    "max_hops": {
      "type": "number",
      "description": "Maximum hop depth (default: 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": "funds recovery already exists for this transaction"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Create Funds Recovery
POST`/api/v2/funds-recoveries`

Initiate a MED 2.0 fraud recovery process for a fraudulent transaction.

Workflow States:

CREATED → Initial state
TRACKED → Tracking graph generated
AWAITING_ANALYSIS → Ready for manual review
ANALYSED → Analysis complete
REFUNDING → Refund process started
COMPLETED → All refunds processed
CANCELLED → Process cancelled

Tracking Graph Parameters:

MinTransactionAmount: R$ 100.00 (default)
MaxTransactions: 500 (default)
HopWindow: 24 hours (default)
MaxHops: 5 (default)

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"
    }
  }
}

List Funds Recoveries
GET`/api/v2/funds-recoveries`

List funds recoveries with optional filters.

URI Parameters

HideShow

creator_ispb: string (optional) Example: 12345678
Filter by creator
status: string (optional) Example: CREATED
Filter by 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
Page number (default: 1)
page_size: number (optional) Example: 20
Items per page (max 100, default: 20)

Funds Recovery ¶

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": "funds recovery not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Get Funds Recovery
GET`/api/v2/funds-recoveries/{id}`

Retrieve a funds recovery by ID.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID
details: boolean (optional) Example: true
Include tracking graph, infraction reports, and refunds

PUT https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "status": "AWAITING_ANALYSIS"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "New status"
    }
  },
  "required": [
    "status"
  ]
}

Responses200400

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "AWAITING_ANALYSIS",
  "analysis_started_at": "2024-01-15T10:40:00Z",
  "last_updated": "2024-01-15T10:40:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "analysis_started_at": {
      "type": "string"
    },
    "last_updated": {
      "type": "string"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "error": "Invalid status transition"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Update Funds Recovery Status
PUT`/api/v2/funds-recoveries/{id}`

Update the status of a funds recovery.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID

Cancel Funds Recovery ¶

POST https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/cancel

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "cancelled_by_ispb": "12345678",
  "cancellation_reason": "Duplicate request"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "cancelled_by_ispb": {
      "type": "string",
      "description": "ISPB of cancelling party (8 chars)"
    },
    "cancellation_reason": {
      "type": "string",
      "description": "Reason (max 500 chars)"
    }
  },
  "required": [
    "cancelled_by_ispb",
    "cancellation_reason"
  ]
}

Responses200400

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CANCELLED",
  "cancelled_at": "2024-01-15T11:00:00Z",
  "cancellation_reason": "Duplicate request",
  "cancelled_by_ispb": "12345678"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "cancelled_at": {
      "type": "string"
    },
    "cancellation_reason": {
      "type": "string"
    },
    "cancelled_by_ispb": {
      "type": "string"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "code": "FR002",
  "error": "funds recovery cannot be cancelled in current state"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Cancel Funds Recovery
POST`/api/v2/funds-recoveries/{id}/cancel`

Cancel a funds recovery process.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID

Start Refund ¶

POST https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/start-refund

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200400

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "REFUNDING",
  "refund_started_at": "2024-01-15T12:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "refund_started_at": {
      "type": "string"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "error": "Invalid status transition. Must be in ANALYSED state"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Start Refund Process
POST`/api/v2/funds-recoveries/{id}/start-refund`

Initiate automated refund workflow after analysis.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID

Tracking Graph ¶

GET https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/tracking-graph

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
  "max_depth_reached": 3,
  "total_transactions": 15,
  "total_persons": 8,
  "total_accounts": 10,
  "generated_at": "2024-01-15T10:35:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "funds_recovery_id": {
      "type": "string"
    },
    "max_depth_reached": {
      "type": "number"
    },
    "total_transactions": {
      "type": "number"
    },
    "total_persons": {
      "type": "number"
    },
    "total_accounts": {
      "type": "number"
    },
    "generated_at": {
      "type": "string"
    }
  }
}

Get Tracking Graph
GET`/api/v2/funds-recoveries/{id}/tracking-graph`

Retrieve the transaction tracking graph.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID

POST https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/tracking-graph

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
  "max_depth_reached": 3,
  "total_transactions": 15,
  "generated_at": "2024-01-15T10:35:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "funds_recovery_id": {
      "type": "string"
    },
    "max_depth_reached": {
      "type": "number"
    },
    "total_transactions": {
      "type": "number"
    },
    "generated_at": {
      "type": "string"
    }
  }
}

Generate Tracking Graph
POST`/api/v2/funds-recoveries/{id}/tracking-graph`

Trigger tracking graph generation (if not already generated).

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID

Infraction Reports ¶

GET https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/infraction-reports

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "reported_ispb": "87654321",
    "reported_account": "123456",
    "report_type: `MULE_ACCOUNT`": "Hello, world!",
    "status": "SENT",
    "sent_at": "2024-01-15T10:40:00Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List Infraction Reports
GET`/api/v2/funds-recoveries/{id}/infraction-reports`

List all infraction reports linked to a funds recovery.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID

MED 2.0 - Infraction Reports ¶

Infraction Reports List ¶

GET https://api.dictra.com.br/api/v2/infraction-reports

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "reported_ispb": "87654321",
    "report_type: `MULE_ACCOUNT`": "Hello, world!",
    "status": "SENT"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Infraction Reports
GET`/api/v2/infraction-reports`

List infraction reports (fraud notifications to receiving banks).

Infraction Report ¶

GET https://api.dictra.com.br/api/v2/infraction-reports/660e8400-e29b-41d4-a716-446655440001

Requestsexample 1

Headers

X-Participant-ISPB: 87654321

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
  "reported_ispb": "87654321",
  "reported_account": "123456",
  "report_type: `MULE_ACCOUNT`": "Hello, world!",
  "status": "SENT",
  "sent_at": "2024-01-15T10:40:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "funds_recovery_id": {
      "type": "string"
    },
    "reported_ispb": {
      "type": "string"
    },
    "reported_account": {
      "type": "string"
    },
    "report_type: `MULE_ACCOUNT`": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "sent_at": {
      "type": "string"
    }
  }
}

Get Infraction Report
GET`/api/v2/infraction-reports/{id}`

Retrieve an infraction report by ID.

URI Parameters

HideShow

id: string (required) Example: 660e8400-e29b-41d4-a716-446655440001
Infraction report UUID

PUT https://api.dictra.com.br/api/v2/infraction-reports/analyse

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 87654321

Body

{
  "analysis_result": "CONFIRMED",
  "analysis_notes": "Account frozen"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "analysis_result": {
      "type": "string",
      "description": "CONFIRMED or REJECTED"
    },
    "analysis_notes": {
      "type": "string"
    }
  },
  "required": [
    "analysis_result"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "ANALYSED",
  "analysed_at": "2024-01-15T11:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "analysed_at": {
      "type": "string"
    }
  }
}

Analyse Infraction Report
PUT`/api/v2/infraction-reports/analyse`

Analyse and respond to an infraction report (receiving bank action).

MED 2.0 - Refund Requests ¶

Refund Requests for Recovery ¶

GET https://api.dictra.com.br/api/v2/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/refunds

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "refund_ispb": "87654321",
    "refund_amount": 500,
    "status": "PENDING",
    "created_at": "2024-01-15T12:00:00Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List Refund Requests
GET`/api/v2/funds-recoveries/{id}/refunds`

List all refund requests for a funds recovery.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Funds recovery UUID

POST https://api.dictra.com.br/api/v2/funds-recoveries/refund

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "refund_ispb": "87654321",
  "refund_account": "123456",
  "refund_amount": 500,
  "transaction_id": "E87654321202401151045XYZ54321"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "refund_ispb": {
      "type": "string"
    },
    "refund_account": {
      "type": "string"
    },
    "refund_amount": {
      "type": "number"
    },
    "transaction_id": {
      "type": "string"
    }
  },
  "required": [
    "refund_ispb",
    "refund_account",
    "refund_amount",
    "transaction_id"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
  "refund_ispb": "87654321",
  "refund_amount": 500,
  "status": "PENDING",
  "created_at": "2024-01-15T12:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "funds_recovery_id": {
      "type": "string"
    },
    "refund_ispb": {
      "type": "string"
    },
    "refund_amount": {
      "type": "number"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Request Refund
POST`/api/v2/funds-recoveries/refund`

Create a refund request for recovered funds.

GET https://api.dictra.com.br/api/v2/funds-recoveries/refund-summary

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "total_refunds": 3,
  "total_amount": 1500,
  "pending": 1,
  "completed": 2,
  "failed": 0
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "total_refunds": {
      "type": "number"
    },
    "total_amount": {
      "type": "number"
    },
    "pending": {
      "type": "number"
    },
    "completed": {
      "type": "number"
    },
    "failed": {
      "type": "number"
    }
  }
}

Get Refund Summary
GET`/api/v2/funds-recoveries/refund-summary`

Get summary of all refunds for a funds recovery.

All Refund Requests ¶

GET https://api.dictra.com.br/api/v2/refund-requests

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "refund_ispb": "87654321",
    "refund_amount": 500,
    "status": "PENDING"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Refund Requests
GET`/api/v2/refund-requests`

List all refund requests across all funds recoveries.

Refund Request ¶

GET https://api.dictra.com.br/api/v2/refund-requests/770e8400-e29b-41d4-a716-446655440002

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
  "refund_ispb": "87654321",
  "refund_account": "123456",
  "refund_amount": 500,
  "status": "PENDING",
  "created_at": "2024-01-15T12:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "funds_recovery_id": {
      "type": "string"
    },
    "refund_ispb": {
      "type": "string"
    },
    "refund_account": {
      "type": "string"
    },
    "refund_amount": {
      "type": "number"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Get Refund Request
GET`/api/v2/refund-requests/{id}`

Retrieve a refund request by ID.

URI Parameters

HideShow

id: string (required) Example: 770e8400-e29b-41d4-a716-446655440002
Refund request UUID

PUT https://api.dictra.com.br/api/v2/refund-requests/complete

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "completion_notes": "Refund processed successfully"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "completion_notes": {
      "type": "string"
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "COMPLETED",
  "completed_at": "2024-01-15T13:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "completed_at": {
      "type": "string"
    }
  }
}

Complete Refund
PUT`/api/v2/refund-requests/complete`

Mark a refund as completed after SPI payment.

POST https://api.dictra.com.br/api/v2/refund-requests/cancel

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "cancellation_reason": "Funds not recovered"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "cancellation_reason": {
      "type": "string"
    }
  },
  "required": [
    "cancellation_reason"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "CANCELLED",
  "cancelled_at": "2024-01-15T13:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "cancelled_at": {
      "type": "string"
    }
  }
}

Cancel Refund
POST`/api/v2/refund-requests/cancel`

Cancel a pending refund request.

Event Notifications ¶

GET https://api.dictra.com.br/api/v2/event-notifications

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "event_type: `CLAIM_DONOR_DEADLINE`": "Hello, world!",
    "claim_id": "C1234567890",
    "scheduled_at": "2024-01-29T10:30:00Z",
    "acknowledged": false
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List Notifications
GET`/api/v2/event-notifications`

List DICT event notifications (claim deadlines, status changes).

POST https://api.dictra.com.br/api/v2/event-notifications/acknowledge

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "notification_ids": [
    "880e8400-e29b-41d4-a716-446655440003"
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "notification_ids": {
      "type": "array"
    }
  },
  "required": [
    "notification_ids"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "acknowledged": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "acknowledged": {
      "type": "number"
    }
  }
}

Acknowledge Notifications
POST`/api/v2/event-notifications/acknowledge`

Mark notifications as acknowledged.

Admin API - Rate Limiting ¶

Institutions List ¶

GET https://api.dictra.com.br/api/v2/admin/institutions?category=A&status=ACTIVE&limit=20&offset=0

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "institutions": [
    {
      "ispb": "00000000",
      "name": "Banco do Brasil",
      "category": "A",
      "status": "ACTIVE",
      "bucket_capacity": 50000,
      "bucket_refill_rate": 25000
    }
  ],
  "total_count": 1,
  "limit": 20,
  "offset": 0
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "institutions": {
      "type": "array"
    },
    "total_count": {
      "type": "number"
    },
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    }
  }
}

List Institutions
GET`/api/v2/admin/institutions?category={category}&status={status}&limit={limit}&offset={offset}`

List all institutions with rate limiting configuration.

URI Parameters

HideShow

category: string (optional) Example: A
Filter by category (A-H)
status: string (optional) Example: ACTIVE
Filter by status
limit: number (optional) Example: 20
Items per page (default: 20)
offset: number (optional) Example: 0
Offset (default: 0)

POST https://api.dictra.com.br/api/v2/admin/institutions

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "ispb": "12345678",
  "name": "Test Bank",
  "category": "H"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string",
      "description": "8-digit ISPB"
    },
    "name": {
      "type": "string"
    },
    "category": {
      "type": "string",
      "description": "Default: H"
    }
  },
  "required": [
    "ispb",
    "name"
  ]
}

Responses201409

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "name": "Test Bank",
  "category": "H",
  "status": "ACTIVE",
  "bucket_capacity": 50,
  "bucket_refill_rate": 2
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "bucket_capacity": {
      "type": "number"
    },
    "bucket_refill_rate": {
      "type": "number"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "code": "CONFLICT",
  "error": "institution already exists"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Create Institution
POST`/api/v2/admin/institutions`

Institution ¶

GET https://api.dictra.com.br/api/v2/admin/institutions/12345678

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200404

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "name": "Test Bank",
  "category": "H",
  "status": "ACTIVE",
  "bucket_capacity": 50,
  "bucket_refill_rate": 2,
  "current_tokens": 48,
  "last_refill": "2024-01-15T12:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "bucket_capacity": {
      "type": "number"
    },
    "bucket_refill_rate": {
      "type": "number"
    },
    "current_tokens": {
      "type": "number"
    },
    "last_refill": {
      "type": "string"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "code": "NOT_FOUND",
  "error": "institution not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Get Institution
GET`/api/v2/admin/institutions/{ispb}`

Get institution with current bucket status and metrics.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
Institution ISPB

PUT https://api.dictra.com.br/api/v2/admin/institutions/12345678

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "name": "Test Bank Updated",
  "status": "INACTIVE"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "name": "Test Bank Updated",
  "status": "INACTIVE"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  }
}

Update Institution
PUT`/api/v2/admin/institutions/{ispb}`

Update institution details.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
Institution ISPB

DELETE https://api.dictra.com.br/api/v2/admin/institutions/12345678

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses204404

This response has no content.

Headers

Content-Type: application/json

Body

{
  "code": "NOT_FOUND",
  "error": "institution not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Delete Institution
DELETE`/api/v2/admin/institutions/{ispb}`

Delete an institution.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
Institution ISPB

Change Category ¶

PATCH https://api.dictra.com.br/api/v2/admin/institutions/12345678/category

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "category": "G",
  "changed_by": "admin@dictra.com"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "New category (A-H)"
    },
    "changed_by": {
      "type": "string",
      "description": "Who made the change"
    }
  },
  "required": [
    "category",
    "changed_by"
  ]
}

Responses200404

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "category": "G",
  "bucket_capacity": 200,
  "bucket_refill_rate": 100,
  "category_changed_at": "2024-01-15T12:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "bucket_capacity": {
      "type": "number"
    },
    "bucket_refill_rate": {
      "type": "number"
    },
    "category_changed_at": {
      "type": "string"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "code": "NOT_FOUND",
  "error": "institution not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Change Institution Category
PATCH`/api/v2/admin/institutions/{ispb}/category`

Change BACEN category (A-H) which updates bucket parameters.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
Institution ISPB

Bucket Status ¶

GET https://api.dictra.com.br/api/v2/admin/institutions/12345678/bucket

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200404

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "capacity": 200,
  "current_tokens": 195,
  "refill_rate": 100,
  "last_refill": "2024-01-15T12:00:00Z",
  "next_refill": "2024-01-15T12:01:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "capacity": {
      "type": "number"
    },
    "current_tokens": {
      "type": "number"
    },
    "refill_rate": {
      "type": "number"
    },
    "last_refill": {
      "type": "string"
    },
    "next_refill": {
      "type": "string"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "code": "NOT_FOUND",
  "error": "bucket not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Get Bucket Status
GET`/api/v2/admin/institutions/{ispb}/bucket`

Get current token bucket status.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
Institution ISPB

POST https://api.dictra.com.br/api/v2/admin/institutions/bucket/reset

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses204

This response has no content.

Reset Bucket
POST`/api/v2/admin/institutions/bucket/reset`

Reset bucket to full capacity (emergency operation).

Institution Metrics ¶

GET https://api.dictra.com.br/api/v2/admin/institutions/12345678/metrics

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "queries_24h": 1500,
  "not_found_24h": 105,
  "not_found_ratio": 0.07,
  "alert_triggered": false,
  "threshold": 0.07
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "queries_24h": {
      "type": "number"
    },
    "not_found_24h": {
      "type": "number"
    },
    "not_found_ratio": {
      "type": "number"
    },
    "alert_triggered": {
      "type": "boolean"
    },
    "threshold": {
      "type": "number"
    }
  }
}

Get Institution Metrics
GET`/api/v2/admin/institutions/{ispb}/metrics`

Get query metrics summary for institution.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
Institution ISPB

System Metrics ¶

GET https://api.dictra.com.br/api/v2/admin/metrics/summary

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "total_institutions": 28,
  "total_queries_24h": 45000,
  "average_not_found_ratio": 0.05,
  "active_alerts": 2
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "total_institutions": {
      "type": "number"
    },
    "total_queries_24h": {
      "type": "number"
    },
    "average_not_found_ratio": {
      "type": "number"
    },
    "active_alerts": {
      "type": "number"
    }
  }
}

Get System Metrics Summary
GET`/api/v2/admin/metrics/summary`

Get system-wide metrics summary.

Alerts ¶

GET https://api.dictra.com.br/api/v2/admin/metrics/alerts

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "alerts": [
    {
      "type": "PARTICIPANT_THRESHOLD",
      "ispb": "12345678",
      "queries_24h": 2000,
      "not_found_ratio": 0.08,
      "threshold": 0.07,
      "triggered_at": "2024-01-15T11:00:00Z"
    }
  ],
  "count": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alerts": {
      "type": "array"
    },
    "count": {
      "type": "number"
    }
  }
}

Get Active Alerts
GET`/api/v2/admin/metrics/alerts`

Get active rate limit alerts (7% participant, 20% user thresholds).

DICT v2.10.0 - Batch Key Validation ¶

Check Keys ¶

POST https://api.dictra.com.br/api/v2/keys/check

Requestsexample 1

Headers

Content-Type: application/json
X-Participant-ISPB: 12345678

Body

{
  "keys": [
    "12345678901",
    "test@example.com",
    "+5511999999999"
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "keys": {
      "type": "array",
      "description": "1-200 keys"
    }
  },
  "required": [
    "keys"
  ]
}

Responses200400429

Headers

Content-Type: application/json

Body

{
  "keys": [
    {
      "key": "12345678901",
      "hasEntry": true
    },
    {
      "key": "test@example.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": "Keys array must contain 1-200 elements"
}

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": "Rate limit exceeded. 70 requests/min allowed"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Batch Validate Keys
POST`/api/v2/keys/check`

Check if multiple keys exist in the DICT (1-200 keys per request).

Rate Limit: 70 requests/min per participant

BACEN v2.10.0 Compliance: Returns hasEntry boolean only (no owner data)

DICT v2.10.0 - CID File Operations ¶

CID Files ¶

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": "Idempotency key"
    }
  },
  "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": "File request with this requestId already exists"
}

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": "Daily limit exceeded. 40 CID files allowed per day"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}

Create CID File
POST`/api/v2/cids/files`

Request a CID batch file for reconciliation (40 files/day limit per participant).

File Generation:

Includes all participant keys with CIDs
Available for 30 days
Contains: keyType, key, CID, ownerTaxId, participantIspb

Rate Limit: 40/day per participant

CID File ¶

GET https://api.dictra.com.br/api/v2/cids/files/990e8400-e29b-41d4-a716-446655440004

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200403404

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": "Access denied to this CID file"
}

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": "CID file not found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Get CID File
GET`/api/v2/cids/files/{fileId}`

Retrieve CID file status and download URL.

URI Parameters

HideShow

fileId: string (required) Example: 990e8400-e29b-41d4-a716-446655440004
CID file UUID

CID Events ¶

GET https://api.dictra.com.br/api/v2/cids/events?eventType=ENTRY_CREATED&cid=E1234567890&fileId=990e8400-e29b-41d4-a716-446655440004&createdAfter=2024-01-01T00:00:00Z&createdBefore=2024-01-31T23:59:59Z&offset=0&limit=50

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440005",
      "eventType": "ENTRY_CREATED",
      "cid": "E1234567890123456789012345678901",
      "entryKey": "12345678901",
      "entryKeyType": "CPF",
      "participantIspb": "12345678",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "totalCount": 1,
  "offset": 0,
  "limit": 50
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "events": {
      "type": "array"
    },
    "totalCount": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "limit": {
      "type": "number"
    }
  }
}

List CID Events
GET`/api/v2/cids/events?eventType={eventType}&cid={cid}&fileId={fileId}&createdAfter={createdAfter}&createdBefore={createdBefore}&offset={offset}&limit={limit}`

List CID events (entry creations, updates, deletions).

Event Types:

ENTRY_CREATED
ENTRY_UPDATED
ENTRY_DELETED
FILE_CREATED
FILE_COMPLETED

URI Parameters

HideShow

eventType: string (optional) Example: ENTRY_CREATED
Filter by event type
cid: string (optional) Example: E1234567890
Filter by CID
fileId: string (optional) Example: 990e8400-e29b-41d4-a716-446655440004
Filter by file ID
createdAfter: string (optional) Example: 2024-01-01T00:00:00Z
ISO 8601
createdBefore: string (optional) Example: 2024-01-31T23:59:59Z
ISO 8601
offset: number (optional) Example: 0
Pagination offset
limit: number (optional) Example: 50
Items per page (1-100, default: 50)

DICT v2.10.0 - Anti-Fraud Statistics ¶

Person Statistics ¶

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 or 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": "Cache timestamp"
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "error": "Invalid taxId format. Must be 11 digits (CPF) or 14 digits (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": "statistics not found for taxId"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Get Person Statistics
GET`/api/v2/entries/statistics/person?taxId={taxId}`

Get aggregated anti-fraud statistics for a person (by CPF/CNPJ).

Statistics Include:

SPI Metrics: Settlement counts (D+90, M+12, M+60)
Fraud Markers: Application frauds, mule accounts, scammer accounts, total fraud amount
Infraction Reports: Open/rejected reports, distinct reporters
Entries: Total registered accounts

Rate Limit: 12,000 requests/min per participant

URI Parameters

HideShow

taxId: string (required) Example: 12345678901
CPF (11 digits) or CNPJ (14 digits)

Key Statistics ¶

GET https://api.dictra.com.br/api/v2/entries/statistics/key?keyType=EMAIL&key=test@example.com

Requestsexample 1

Headers

X-Participant-ISPB: 12345678

Responses200400404

Headers

Content-Type: application/json

Body

{
  "keyType": "EMAIL",
  "keyValue": "test@example.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": "Invalid keyType. Must be one of: 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": "statistics not found for key"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}

Get Key Statistics
GET`/api/v2/entries/statistics/key?keyType={keyType}&key={key}`

Get aggregated anti-fraud statistics for a PIX key.

Statistics Include:

SPI Metrics: Settlement counts
Fraud Markers: Application frauds, distinct reporters
Infraction Reports: Open/rejected reports
Entries: Distinct accounts registered with this key

Rate Limit: 12,000 requests/min per participant

URI Parameters

HideShow

keyType: string (required) Example: EMAIL
EMAIL, PHONE, CPF, CNPJ, EVP
key: string (required) Example: test@example.com
Key value

Generated by aglio on 24 Jan 2026

API Endpoint

Authentication ¶

Rate Limiting ¶

User Bucket (PI-PayerId) ¶

Participant Bucket (ISPB) ¶

Institution Categories ¶

Headers ¶

Request Headers ¶

Response Headers ¶

Error Codes ¶

HTTP Status Codes ¶

DICT Error Codes ¶

Health ¶

Health Check ¶

Headers

Body

Schema

Get Health StatusGET/health

Readiness Check ¶

Headers

Body

Schema

Get Readiness StatusGET/ready

Core DICT - PIX Keys ¶

Entry ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Create PIX KeyPOST/api/v2/entries

Entry by Key ¶

Headers

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Get PIX KeyGET/api/v2/entries/{key}?keyType={keyType}

Headers

Headers

Body

Schema

Headers

Body

Schema

Delete PIX KeyDELETE/api/v2/entries/{key}?keyType={keyType}

Entry by CID ¶

Headers

Headers

Body

Schema

Headers

Body

Schema

Get Entry by CIDGET/api/v2/entries/cid/{cid}

Core DICT - Claims ¶

Claims for Key ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Create ClaimPOST/api/v2/entries/{key}/claims

Headers

Authentication

Rate Limiting

User Bucket (PI-PayerId)

Participant Bucket (ISPB)

Institution Categories

Headers

Request Headers

Response Headers

Error Codes

HTTP Status Codes

DICT Error Codes

Get Health Status
GET`/health`

Get Readiness Status
GET`/ready`

Create PIX Key
POST`/api/v2/entries`

Get PIX Key
GET`/api/v2/entries/{key}?keyType={keyType}`

Delete PIX Key
DELETE`/api/v2/entries/{key}?keyType={keyType}`

Get Entry by CID
GET`/api/v2/entries/cid/{cid}`

Create Claim
POST`/api/v2/entries/{key}/claims`

List Claims for Key
GET`/api/v2/entries/{key}/claims`

Update Claim
PATCH`/api/v2/entries/{key}/claims/{claimId}`

List All Claims
GET`/api/v2/claims?role={role}&status={status}&page={page}&pageSize={pageSize}`

Get Claim
GET`/api/v2/claims/{claimId}`

Create Funds Recovery
POST`/api/v2/funds-recoveries`

List Funds Recoveries
GET`/api/v2/funds-recoveries`

Get Funds Recovery
GET`/api/v2/funds-recoveries/{id}`

Update Funds Recovery Status
PUT`/api/v2/funds-recoveries/{id}`