Identificadores e IDs

A API ApexPy utiliza um sistema padronizado de identificadores para facilitar o rastreamento e integração.

Cash In (Charges)

ID da API ApexPy

Todas as cobranças retornadas pela API possuem um ID no formato:

ci_{id_interno}

Exemplo: ci_123

ci_ é o prefixo fixo para Cash In (cobranças: PIX, Cartão, Boleto)
{id_interno} é o ID numérico único da cobrança no banco de dados
Este ID é usado em todas as requisições da API (consultar, reembolsar, cancelar)

External ID

Você pode enviar um external_id opcional ao criar uma cobrança:

{
  "amount": 10000,
  "payment_method": "pix",
  "external_id": "pedido_12345"
}

Este ID é armazenado e pode ser usado para rastreamento no seu sistema. Ele não substitui o ID da API, mas facilita a busca e integração com seus sistemas internos.

IDs das Adquirentes

Internamente, a ApexPy armazena os IDs das transações nas adquirentes:

Método	Campo na API	Descrição
PIX	`pix.txid`	Transaction ID (TXID) do PIX retornado pela adquirente. Este é o identificador único da transação PIX no sistema bancário.
Cartão	`acquirer_transaction_id`	ID da transação na adquirente de cartão. Armazenado internamente, mas não exposto diretamente na resposta da API.
Boleto	`acquirer_transaction_id`	ID da transação na adquirente de boleto. Armazenado internamente.

Nota: Os IDs das adquirentes são armazenados internamente para rastreamento e reconciliação. Para operações na API, sempre use o ID da ApexPy (ci_123).

Cash Out (Payouts)

ID da API ApexPy

Todos os saques retornados pela API possuem um ID no formato:

co_{id_interno}

Exemplo: co_456

co_ é o prefixo fixo para Cash Out (saques via PIX)
{id_interno} é o ID numérico único do saque no banco de dados
Este ID é usado em todas as requisições da API (consultar saque)

IDs das Adquirentes BaaS

Para saques via PIX, a ApexPy armazena o end_to_end_id retornado pelo provedor BaaS:

Campo	Descrição
`end_to_end_id`	End-to-End ID do PIX retornado pelo provedor BaaS. Este é o identificador único da transferência PIX no sistema bancário. Armazenado internamente e usado para rastreamento e reconciliação.

Uso dos IDs

Consultar Cobrança

GET /v1/charges/ci_123

Você pode usar o ID com ou sem o prefixo. A API aceita ambos os formatos:

ci_123 (recomendado)
123 (também funciona)

Consultar Saque

GET /v1/payouts/co_456

Da mesma forma, você pode usar:

co_456 (recomendado)
456 (também funciona)

Reembolsar

POST /v1/charges/ci_123/refund

Cancelar

POST /v1/charges/ci_123/cancel

Boas Práticas

Sempre use o ID completo com prefixo (ci_123, co_456) para maior clareza
Armazene o external_id junto com o ID da API para facilitar a busca no seu sistema
Use external_id para rastreamento - ele permite mapear cobranças da ApexPy com pedidos do seu sistema
Não confie nos IDs das adquirentes - eles podem mudar ou não estar disponíveis. Use sempre o ID da ApexPy

Exemplo Completo

// Criar cobrança com external_id
POST /v1/charges
{
  "amount": 10000,
  "payment_method": "pix",
  "external_id": "pedido_12345",
  "customer": {
    "name": "João Silva",
    "email": "[email protected]"
  }
}

// Resposta
{
  "success": true,
  "data": {
    "id": "ci_789",           // ID da ApexPy (Cash In)
    "external_id": "pedido_12345",  // Seu ID externo
    "status": "pending",
    "pix": {
      "txid": "E12345678202511281234567890123456"  // ID da adquirente (PIX)
    }
  }
}

// Consultar usando o ID da ApexPy
GET /v1/charges/ci_789

// Ou buscar por external_id (se implementado)
GET /v1/charges?external_id=pedido_12345