Sua aplicação inicia um pagamento, reembolso ou outra operação suportada.
Guia para desenvolvedores
Comandos síncronos. Resultados financeiros assíncronos.
Operações financeiras muitas vezes continuam após a resposta inicial. Use comandos para iniciar trabalho, eventos para avisar os sistemas que precisam reagir e consultas para obter o estado operacional mais recente sem acoplar a aplicação a callbacks específicos de provedores.
01Comando
02Resposta inicial
03Processamento do provedor
04Evento
05Consulta de estado
Limite de integração
Eventos carregam mudanças do ciclo, não a complexidade do provedor
As aplicações devem reagir ao significado de negócio do evento em vez de aprender o modelo de callback de cada banco, PSP, adquirente ou provedor de terminal. O limite da plataforma mantém o comportamento específico do provedor atrás de um modelo de integração mais estável.
A resposta síncrona identifica a operação e seu estado atual.
Autenticação, atividade de terminal ou processamento do provedor podem continuar de forma assíncrona.
Uma mudança do ciclo de vida é entregue aos sistemas que precisam reagir.
O sistema consumidor pode consultar o estado atual quando precisa de contexto operacional autoritativo.
Padrão comprovado
Padrões de eventos semânticos
A experiência de integração em produção mostra o valor de notificações de mudança de estado e conclusão em pagamentos online e outros métodos. O padrão reutilizável é o ciclo semântico, não o nome específico do evento de um provedor.
- Status do pagamento alterado — a operação passou para um novo estado de pagamento.
- Autenticação concluída — a etapa de autenticação do cliente chegou a um resultado.
- Reembolso atualizado — um ajuste pós-pagamento mudou de estado.
- Operação de terminal ou canal concluída — um fluxo assíncrono do canal chegou a um resultado.
Envelope conceitual de evento — não é um schema atual de webhook
{
"event": "semantic-lifecycle-event",
"transaction_id": "durable-transaction-id",
"reference": "your-business-reference",
"state": "...",
"occurred_at": "..."
}Modelo de implementação
Orientação de integração
Estes padrões descrevem comportamentos de integração comprovados em sistemas de produção. Eles definem o modelo técnico; não prometem que a API atual da Zopio utilizará um endpoint, campo ou formato de contrato específico.
Trate eventos como notificações
Use o evento para acionar trabalho posterior sem ligar a lógica de negócio ao formato de callback de um provedor.
Preserve a identidade da transação
Mantenha cada atualização assíncrona ligada ao mesmo contexto transacional durável.
Consulte quando o estado atual importar
Quando um fluxo precisar da verdade operacional mais recente, use uma consulta de estado em vez de depender de um único callback.
Projete consumidores tolerantes a repetição
Sistemas posteriores devem reconhecer atualizações já processadas e evitar duplicar ações de negócio.
Mantenha diferenças de canal atrás do limite
Fluxos online, de terminal e pagamentos alternativos podem exibir comportamentos diferentes mantendo os mesmos princípios de integração.
Continuar explorando
Falar sobre sua integração