Especificações das trocas REST

Os Web Services usam os princípios comuns das API REST. O formato de trocas utilizado é JSON.

Autenticação

A API REST usa a autenticação básica Para maiores informações, consultar: Fase de autenticação. Para encontrar suas chaves, consulte o artigo seguinte: Requisitos.

Parâmetros da solicitação

O aplicativo espera um JSON válido como entrada de solicitação. Por exemplo, Charge/SDKTest interpretará o objeto Type/String como valor de entrada.

A chamada deve ser realizada da seguinte maneira:

{
    "value": "my testing value"
}
/** 
 * Initialize the SDK 
 * Please update your keys in keys.php
 */
$client = new Lyra\Client();  

/**
 * I send test data
 */
$store = array("value" => "my testing value");
$response = $client->post("V4/Charge/SDKTest", $store);

Parâmetros da resposta

Quando o Web Service responde, ele retorna:

{
    "webService":"Charge/SDKTest",
    "version":"V4",
    "applicationVersion":"4.1.2",
    "status":"SUCCESS",
    "answer": {
        "value":"my testing value",
        "_type":"V4/Type/String"
    },
    "ticket":null,
    "serverDate":"2018-10-02T16:13:57+00:00",
    "applicationProvider":"PAYZEN",
    "metadata":null,
    "_type":"V4/WebService/Response"
}

O objeto solicitado é retornado em um objeto de resposta genérico que:

CONFIGURAÇÃO TIPO DESCRIÇÃO
webService string web service chamado, formato: [namespace]/[web_service_name]
versão string versão da API
status string status da resposta: SUCCESS ou ERROR
answer objeto a resposta profissão (if status is SUCCESS)
ticket string número de ticket para enviar ao suporte (não implementado)
applicationProvider string plataforma que realiza o serviço
applicationVersion string versão do aplicativo
metadata objeto restrito ao uso interno
serverDateTime string data do servidor que respondeu, em UTC
_type string tipo do objeto. Começa sempre pelo número de versão

Gerenciamento dos erros

Em caso de erro do Web Service:

{
    "amount": -1
}

A resposta é:

{
  "webService": "Charge/CreatePayment",
  "version": "V4",
  "applicationVersion": "4.5.1",
  "status": "ERROR",
  "answer": {
    "errorCode": "INT_902",
    "errorMessage": "web-service input data validation error",
    "detailedErrorCode": null,
    "detailedErrorMessage": "can't decode JSON data : {\n    \"amount\":   -1,\n}",
    "ticket": "null",
    "_type": "V4/WebService/WebServiceError"
  },
  "ticket": null,
  "serverDate": "2018-12-10T19:27:32+00:00",
  "applicationProvider": "PAYZEN",
  "metadata": null,
  "_type": "V4/WebService/Response"
}

O Web Service falhou e retorna um objeto V3.1/WebService/WebServiceError:

CONFIGURAÇÃO TIPO DESCRIÇÃO
errorCode string Código de erro (no formato [PREFIXO]_[CÓDIGO])
errorMessage string Mensagem de erro
detailedErrorCode string Código de erro detalhado (ou nulo)
detailedErrorMessage string Mensagem detalhada (ou null)

Para maiores detalhes sobre os erros, consultar: Códigos de erro.

Por que a API não é totalmente RESTful?

Decidimos desenvolver uma API da forma mais simples que puder para evitar erros comuns:

Usamos somente o método POST.

Assim, evitamos questões frequentes sobre qual método usar. É SEMPRE O POST.

Todas as configurações de solicitação são enviadas sob a forma de um objeto JSON:

  • Há apenas uma maneira de enviar configurações (sem acrescentar nada ao URL).
  • Os jornais ficam mais simples.
  • A API responde sempre HTTP 200

Não é portanto necessário gerar diversos códigos de status HTTP, a resposta é sempre 200. O status do Web Service pode ser consultado dentro do objeto JSON.

Data e hora

O objeto datetime está no formato ISO 8601.

O Web Service aceita todos os fusos horários tais como:

  • 2015-11-19T16:56:57+00:00
  • 2015-11-19T16:56:57+01:00
  • 2015-11-19T16:56:57+Z

O servidor sempre retorna o objeto datetime no fuso horário UTC (GMT+00):

  • 2015-11-19T16:56:57+00:00

O servidor nunca retorna 2015-11-19T16:56:57+Z

Valores nulos

Os valores nulos não obrigatórios são automaticamente ausentes da resposta. Ou seja, uma propriedade nula se encontra na resposta somente si a chave se tornou obrigatória, e se null for um valor aceitável.