Machado Do Kratos

O que é o machado do kratos

É uma biblioteca em PHP desenvolvida pela comunidade para facilitar a integração com a API do Kratos, a plataforma de pagamentos da Stone. O repositório original se chama "machado" e funciona como um client mais enxuto do que o SDK oficial, com menos dependências e uma interface mais direta. A instalação padrão é via Composer. Você adiciona a dependência no composer.json ou roda a linha abaixo no terminal do seu projeto.

composer require agp-consultoria/kratos-machado Depois disso, você instancia o cliente passando as credenciais da sua conta Stone.

instalando e configurando o machado do kratos

Primeiro, certifique-se de que está usando PHP 8.1 ou superior. A versão mais recente da biblioteca quebra compatibilidade com versões antigas propositalmente, porque o autor optou por tipagem estrita em tudo. Após instalar, você precisa configurar suas credenciais. O ambiente de homologação usa chaves diferentes das de produção, então deixe isso separado desde o início. Crie um arquivo de configuração com as informações de cliente_id, cliente_secret e o ambiente.

$client = new Machado\Client([
    'client_id' => 'seu_client_id',
    'client_secret' => 'seu_client_secret',
    'environment' => 'homologacao'
]);

Eu configurei a chamada de pix usando o método correto de criação de txid. A documentação oficial da Stone às vezes não menciona que o campo "expiresAt" é obrigatório para gerar QR Code estático, mas o machado trata isso automaticamente se você passar a data de expiração na hora de chamar o endpoint de pagamento.

como fazer uma cobrança com machado do kratos

Para criar uma cobrança por cartão, você chama o método apropriado passando os dados do cartão tokenizados ou usando o token do checkout Stone. O fluxo mais comum é:

1. Gerar o token do cartão no frontend com o checkout Stone.
2. Receber esse token no backend.
3. Passar o token para o machado criar a cobrança.

O código ficaria assim na prática.

$cobranca = $client->vendas()->criar([
    'token' => 'tok_test_123456',
    'amount' => 10000,
    'installments' => 1,
    'softDescriptor' => 'MINHALOJA'
]);

O amount é sempre em centavos. Se você passar 100, vai cobrar R$ 1,00 em vez de R$ 100,00. Esse é o erro mais comum que eu vejo happening em projetos novos.

consulta de transações e status

Para verificar o status de uma cobrança, use o método de consulta passando o identificador da transação retornado na criação.

$status = $client->vendas()->consultar('transacao_id_aqui');

Isso retorna um objeto com o status atual, se foi aprovado, em análise ou recusado. O status "em análise" é mais frequente do que parece, especialmente para compras acima de R$ 500,00 sem histórico anterior da operadora.

problemas práticos que eu encontrei

A eu precisei processar um refund parcial de uma venda que já tinha sido confirmada. O machado suporta isso, mas a forma como a Stone trata refunds parciais em vendas fracionadas pode causar inconsistência se você não passar o valor exato em centavos. Uma vez eu passei 999 em vez de 1000 e a API retornou erro 400 sem mensagem clara no corpo da resposta. A workaround foi fazer uma consulta da venda original, extrair o valor exato e usar aquele valor para o refund. Também notei que o campo "softDescriptor" tem limite de 13 caracteres. Se você passar mais, a API silencia o erro e corta o texto. Não gera exception, só corta. Fique atento a isso se o nome da sua loja for grande.

limitações e quando não usar

O machado não acompanha todas as atualizações da API da Stone no mesmo ritmo que o SDK oficial. Se você precisar de recursos mais recentes como assinatura recorrente avançada ou split de pagamento com regras complexas, talvez o SDK oficial seja mais seguro. Outro ponto: a biblioteca não vem com logging integrado. Você precisa configurar seu próprio PSR-3 para rastrear chamadas e erros. Isso é simples, mas exige configuração extra que o SDK oficial já traz embutido.

Se o volume da sua operação for alto, considere manter o SDK oficial. O machado funciona bem para projetos menores ou media complexidade, onde a simplicidade da API ajuda mais do que a abrangência de endpoints.

baixando o machado do kratos

O repositório oficial está disponível no GitHub. Você pode clonar o projeto ou instalar via Composer usando a referência direta do pacote. Para ver a documentação completa com todos os métodos disponíveis, acesse o repositório e leia o README atualizado. As mudanças de versão são anotadas no changelog, então confira antes de atualizar em produção.

Eu recomendo sempre testar todas as rotas críticas no ambiente de homologação antes de liberar para produção. A Stone pode fazer atualizações nos endpoints sem aviso prévio, e ter cobertura de teste evita surpresas.