GraphQL

Alguns serviços, como certos PBMs, descrevem a operação e os campos desejados dentro da própria mensagem, em vez de usar um endereço diferente para cada recurso. Reconhecer essa estrutura ajuda a separar os erros de execução das recusas de negócio.

Esquema, query e mutation

O GraphQL é uma linguagem de consulta e um modelo de execução baseados em um esquema, a descrição dos tipos e dos campos que o serviço oferece. Quem chama escolhe os campos que quer receber na resposta. Uma chamada GraphQL tem estas partes:

• query: a operação de leitura.
• mutation: a operação de alteração ou de ação, como a criação de uma pré-autorização.
• variables: os valores enviados separados do texto da operação.
• operationName: o nome da operação, quando a mensagem traz mais de uma.

Os nomes das operações e dos campos, como preAutorizarVenda, são definidos pelo fornecedor no esquema, e não pelo padrão GraphQL.

O transporte sobre HTTP

A linguagem não exige um transporte, mas o uso comum é sobre HTTP, em um endereço único, como /graphql. A chamada usa POST, com um JSON que leva o texto da operação no campo query e, quando necessário, os campos variables e operationName. O campo query leva o texto de qualquer operação, inclusive de uma mutation. Uma leitura também pode usar GET quando o servidor aceita, e as mutations usam POST.

A resposta e as camadas do resultado

A resposta GraphQL separa o resultado em partes:

• data: os dados produzidos pela execução;
• errors: os erros de validação ou de execução, que podem aparecer junto com dados parciais;
• os campos de negócio dentro de data, como uma situação e um código definidos pelo fornecedor.

Uma resposta com o código 200 pode trazer erros ou um resultado parcial, e o comportamento depende do tipo de conteúdo e da implementação. O status HTTP, o campo errors e os campos de negócio são lidos juntos antes de concluir se uma venda foi autorizada.

Um exemplo de PBM

No PBM, uma pré-autorização segue estes passos, com os nomes definidos pelo esquema do fornecedor:

1. a aplicação chama a mutation login com o usuário e a senha, quando o contrato prevê esse mecanismo;
2. a resposta traz o token em data.login.token, e o início eyJ sugere um JWT, sem comprovar o formato nem a validade;
3. a aplicação chama a mutation preAutorizarVenda com a loja, o cliente e os produtos, com o token no cabeçalho Authorization;
4. a aplicação pede, na resposta, o identificador da autorização, a situação, o código e a mensagem.

Uma resposta simplificada com recusa fica assim:

• {"data":{"preAutorizarVenda":{"autorizacao":"PBM-0001","situacao":"ERRO","codigo":14,"mensagem":"Cartao invalido"}}}: o PBM registrou a operação PBM-0001 e recusou a pré-autorização com o código 14.

Quando o contrato define esses campos dessa forma, o retorno registra a recusa da pré-autorização por cartão inválido. O identificador PBM-0001 serve para o rastreio mesmo com erro e não equivale a um benefício autorizado.

Erros, dados parciais e efeitos

Um erro de sintaxe ou de validação impede a execução da operação. Um erro durante a execução pode deixar data parcial junto com errors, e o campo path de cada erro, quando existe, indica o campo afetado.

Uma mutation com mais de uma ação não desfaz automaticamente as ações anteriores quando uma delas falha, porque o GraphQL não oferece, por si, uma transação única. Antes de repetir uma pré-autorização ou uma venda, os efeitos das partes executadas e a proteção prevista pelo PBM são confirmados.

Pedir menos campos reduz a resposta, mas a omissão da situação ou do identificador dificulta a confirmação do resultado. A seleção preserva os campos necessários à interpretação, ao acompanhamento e ao suporte.

Um campo de data da resposta, como o momento da criação, pode representar um momento de negócio diferente do horário do log. A letra Z no fim de um horário indica UTC, e a conversão para o fuso local vem antes da comparação com o log.