A plataforma é construída em quatro camadas que cooperam entre si. Leituras e escritas vindas dos clientes da API fluem para baixo através das camadas; atualizações vindas dos parceiros de processamento fluem para cima, de forma assíncrona, por meio de webhooks e jobs em segundo plano. Esta página percorre cada camada, o ciclo de vida de uma requisição típica e as duas peças de infraestrutura que sustentam o conjunto: o sistema de jobs e o sistema de webhooks.

​
As quatro camadas

​
1. Camada de Integração com Adquirência

É aqui que a plataforma conversa com os parceiros de processamento externos. Cada parceiro possui seu próprio cliente.

Parceiro de processamento principal

Cliente HTTP com autenticação segura baseada em chaves e certificado mútuo. Suporta diferentes modos de operação:
  • Requisição padrão de marketplace.
  • Requisição sem o prefixo de marketplace.
  • Requisição usando a base mais recente da API.
Possui retry embutido com backoff exponencial e jitter para erros 5xx e 429. Quando envia anexos multipart, omite automaticamente o cabeçalho de tipo de conteúdo JSON.

Parceiro de processamento alternativo

Cliente HTTP com autenticação baseada em certificado (mTLS). Faz uma única chamada para obter um token de acesso via client_credentials e, em seguida, envia-o como Authorization: Bearer ... nas rotas autenticadas.
Adicionar um novo parceiro de processamento significa adicionar um módulo irmão com seu próprio cliente e um pequeno conjunto de pontos de extensão na camada de transações. A camada unificada acima permanece inalterada.

​
2. Camada de Processamento de Transações (sales)

O módulo sales mantém a verdade específica do adquirente. Os registros aqui espelham o que existe no parceiro de processamento, usando um identificador externo como chave única. Os modelos incluem Transaction, Receivable, Document, SplitRule, PaymentMethod, OnlineSellPayment, além de modelos de ponto de venda e de transferência. Cada modelo expõe um método de atualização que cria ou atualiza sua contraparte na camada unificada. O módulo sales também hospeda o despachante de webhooks da adquirência.
As vendas de um dos parceiros atualmente fluem por meio de visões e serializadores dedicados em seu próprio módulo em vez do módulo sales, mas o mesmo padrão de propagação Sales-para-Unificado se aplica.

​
3. Camada de Dados Unificada (unified)

A camada unificada é agnóstica em relação ao adquirente. Todo endpoint de leitura acessado pelo painel ou pelo lojista passa por aqui. Modelos principais:
  • unified.Account — toda conta de lojista, sub-lojista ou parceiro de canal.
  • unified.Transaction, unified.Receivable, unified.AccountDeposit, unified.Document, unified.PointOfSale, unified.TokenizedCard.
  • unified.Split — configuração de comissões por conta.
  • unified.metrics.* — tabelas pré-agregadas (vendas por data, recebíveis esperados por conta/data/produto etc.).
Todos esses modelos estendem uma base abstrata comum que adiciona campos para identificador externo, status reportado pelo adquirente, status interno e marca temporal da última atualização. É assim que uma linha unificada lembra de qual registro de adquirência ela veio. Consulte Modelo de dados unificado para o padrão completo.

​
4. Camada de Lógica de Negócio

Os módulos de domínio ficam acima da camada unificada. Eles não chamam o parceiro de processamento diretamente — criam recursos unificados (ou recursos de sales que se propagam para a camada unificada) e deixam as camadas inferiores fazerem o trabalho.
  • seller — Dados de KYC, endereços, sócios, dados bancários. Envia o cadastro para a infraestrutura de processamento.
  • plans — Planos de pagamento (configurações de parcelamento) e planos de split (modelos de comissão referenciados por unified.Split).
  • event — Bilheteria de eventos. Cada pagamento de checkout de evento é vinculado a uma unified.Transaction; as tabelas de métricas do evento são atualizadas atomicamente quando o status do checkout muda.
  • subscriptions — Cobrança recorrente. O pagamento da assinatura aponta para uma unified.Transaction; a atualização de status é acionada a partir do fluxo de webhooks da camada de transações.
  • uniconta — Contas virtuais que se conciliam contra depósitos e recebíveis.
  • seller_integrations — Chaves de API e webhooks de saída. Após uma atualização de transação, lojistas inscritos no evento transaction.update.status recebem uma chamada POST.

​
Ciclo de vida de uma requisição típica

Um caminho comum: um usuário do painel lista as transações de um lojista. Pontos-chave:
  • A autenticação é tratada por um autenticador unificado que entende tanto JWTs quanto chaves de API de lojista. Quem casar com o token primeiro vence.
  • O controle de acesso para URLs com escopo de lojista é verificado contra o registro de acessos (usuário → conta → permissões). Superusuários têm passe livre.
  • A maior parte dos endpoints de leitura vive na camada unificada e está aninhada sob sellers/{sellers_pk}/.
  • A paginação segue um padrão único da plataforma; veja Convenções.
Para escritas (criar/atualizar) o mesmo caminho se aplica, somado a um efeito colateral: a persistência do modelo normalmente dispara um job em segundo plano para empurrar a alteração para o adquirente ou para atualizar dados relacionados.

​
O sistema de jobs

O módulo de jobs é uma fila persistida no banco de dados na qual outros módulos registram manipuladores. É o caminho pelo qual a plataforma executa qualquer coisa que converse com um adquirente ou que precise ocorrer de forma assíncrona.

​
Registro de jobs

Cada módulo que possui jobs os declara na sua etapa de inicialização: 
registra_job('fetch_transaction', manipulador_de_transacao)
registra_job(
    'fetch_receivables',
    manipulador_de_recebiveis,
    precondicao=precondicao_de_recebiveis,
)
O nome do job é uma string; o manipulador recebe os parâmetros nomeados e um logger.

​
Enfileiramento de jobs

Jobs são enfileirados por meio de uma rotina de enfileiramento que aceita o nome do job, um identificador de recurso e parâmetros adicionais (ou pelos auxiliares específicos de cada módulo). A rotina de enfileiramento deduplica pela combinação (identificador do recurso, tipo do job): se já existe um job em estado WAITING (ou WAITING_PRECONDITION) para o mesmo par, ela retorna o existente em vez de criar uma duplicata. Um parâmetro de execução imediata faz o job rodar inline na mesma requisição (usado pelo despachante de webhooks para caminhos rápidos). Caso contrário, o job permanece WAITING até que o executor o pegue.

​
Execução de jobs

python manage.py runjobs --batch-size 10
O comando de execução roda em laço:
  1. Conta jobs WAITING mais jobs WAITING_PRECONDITION cuja janela de próxima verificação já passou.
  2. Dentro de uma transação, reivindica até batch_size linhas usando SELECT ... FOR UPDATE SKIP LOCKED, de modo que múltiplos executores em múltiplos contêineres possam rodar com segurança em paralelo.
  3. Para cada job reivindicado, executa-o:
    • Se o tipo de job tem uma precondição, ela é rodada primeiro. Precondições falhas são reagendadas com backoff de 3, 5, 10, 15 e 30 minutos. Após cinco verificações falhas, o job é marcado como ERROR.
    • Caso contrário (ou depois que a precondição passa), o manipulador é executado. O resultado é registrado como SUCCESS ou ERROR; exceções são reportadas para a telemetria centralizada.
  4. Envia um heartbeat a cada ciclo.

​
Status de jobs

StatusSignificado
WAITINGEnfileirado, ainda não reivindicado.
WAITING_PRECONDITIONA precondição falhou pelo menos uma vez; será reverificada na janela seguinte.
PROCESSINGReivindicado e em execução pela primeira vez.
REPLAYINGReivindicado novamente após uma tentativa anterior (retry ou replay manual).
SUCCESSConcluído sem exceção.
ERRORFalha definitiva (exceção ou precondição esgotada).

​
Encadeamento de jobs

Jobs costumam disparar outros jobs. Um encadeamento típico após um evento de transação: 
fetch_transaction
  ├── update_unified_transaction_job   (via persistência da transação)
  ├── fetch_receivables                (via persistência da transação)
  │     └── update_receivables_from_acquirer
  └── fetch_pos                        (se um POS estiver envolvido)

​
O sistema de webhooks

Webhooks da adquirência chegam ao endpoint dedicado. O ponto de entrada é intencionalmente enxuto.

​
Fluxo de entrada

  • Todo payload recebido é persistido como ReceivedWebhookCall para reprocessamento e auditoria.
  • Ouvintes são registrados a partir da etapa de inicialização de cada módulo. Hoje apenas o despachante da camada de transações está registrado, mas o registro suporta múltiplos.
  • O despachante inspeciona event['type'] e enfileira o job apropriado (transação, recebível, transferência, lojista, documento, conta bancária).
Um webhook falho pode ser reprocessado via rotina dedicada de replay.

​
Fluxo de saída

Lojistas podem registrar seus próprios webhooks sob /integrations/webhooks/.... Após uma transação de venda ser atualizada, uma rotina de despacho serializa a transação e a envia via POST para cada webhook registrado pelo lojista. O nome do evento é transaction.update.status. Consulte Webhooks e jobs para a taxonomia completa de eventos e procedimentos de replay.

​
Como os parceiros de processamento se encaixam

O contrato que uma integração com um parceiro de processamento precisa satisfazer:
1

Cliente

Um cliente HTTP que encapsula autenticação, segurança de transporte e retries.
2

Modelos na camada de transações

Modelos de domínio que espelham os registros do parceiro, com um identificador externo único e um método de atualização para a camada unificada.
3

Ouvinte de webhook

Uma função registrada no sistema de webhooks que traduz eventos em enfileiramentos de jobs.
4

Manipuladores de jobs

Jobs do tipo fetch_* que leem o estado autoritativo no parceiro e atualizam o modelo da camada de transações. A persistência do modelo se encarrega de propagar para a camada unificada.
5

Ponte para a camada unificada

O modelo unificado resolve sua conta pelo identificador externo do lojista e copia os campos normalizados.

​
Guias relacionados

Modelo de dados unificado

Por que a camada unificada existe e como os dados fluem até ela.

Webhooks e jobs

Tipos de eventos, replay, deduplicação e agendamentos.

Autenticação e acesso

JWT versus chave de API, a tabela de acessos e códigos de permissão.

Fluxo de transação

Um passo a passo concreto desde o link de checkout até a liquidação do recebível.