Valide seu payload
Antes de integrar de verdade, mande o JSON que o seu sistema produz para POST /api/validate e receba, campo a campo, o que está de acordo com esta documentação e o que não está.
Não é necessário autenticação, nada é gravado e nenhuma transação é criada — a comparação é feita contra o mesmo arquivo que gera a página que você está lendo.
Requisição
POST https://developers.guper.co/api/validate
Content-Type: application/json
| Campo | Obrigatório | Descrição |
|---|---|---|
path |
sim¹ | A rota que você chama, como /api/loyalty/rewardByOrder. |
method |
não | Padrão POST. |
endpoint |
sim¹ | Alternativa ao path: o caminho da página, como loyalty/checkout/reward-by-order. |
body |
sim | O corpo que a sua integração envia. |
¹ Informe path ou endpoint.
{
"path": "/api/loyalty/rewardByOrder",
"body": {
"interface": "generic",
"storeId": "1",
"client": { "name": "Tintim", "Entity": "Legal" },
"items": [ { "id": "1", "name": "Bolsa", "quantity": "1", "price": 9900 } ]
}
}
Resposta
{
"ok": false,
"endpoint": "loyalty/checkout/reward-by-order",
"title": "Reward by Order",
"summary": { "unknown": 1, "missing": 0, "type": 1, "value": 0 },
"findings": [
{
"path": "client.Entity",
"kind": "unknown",
"message": "Campo nao existe neste endpoint.",
"didYouMean": "entityType"
},
{
"path": "items[0].quantity",
"kind": "type",
"message": "Esperado integer, veio string.",
"expected": ["integer"],
"got": "string"
}
]
}
ok é true quando não há nenhum achado. Cada achado tem um kind:
kind |
Significa |
|---|---|
unknown |
O campo não existe neste endpoint. Quando o nome é parecido com um campo nosso, didYouMean traz o correto. |
missing |
Campo obrigatório não foi enviado. |
type |
O tipo não bate — por exemplo, "1" onde se espera um inteiro. |
value |
O valor está fora da lista aceita. Caixa errada ("Legal" em vez de legal) é apontada explicitamente. |
A resposta traz ainda fields, o inventário de todos os campos documentados daquele endpoint, dizendo quais vieram no seu payload — útil para descobrir o que você poderia estar enviando e não está.
O que ele não verifica
A conferência é de forma, contra a documentação. Ela não conhece a sua organização, então não diz se aquele storeId existe, se a interface está cadastrada, nem se o valor em centavos está na escala certa. Payload aprovado aqui ainda pode ser recusado pela API por esses motivos.
Por que isso existe
Chave de objeto é sensível a maiúsculas e minúsculas. Um campo com o nome errado não é lido — e, por desenho, campo desconhecido é ignorado em silêncio, sem erro. Já aconteceu de uma integração enviar client.Entity por dois meses achando que estava informando o tipo de entidade do cliente: o campo se chama entityType, nada era lido e nenhum erro aparecia. Um teste aqui, no primeiro dia, teria mostrado as duas coisas.