LIBERAÇÃO

Para utilização desta integração é necessário ter a rotina de Trade in habilitada com suas devidas configurações e parametrizações (importante alinhar com o gerente de relacionamento antes do início do projeto) e a Operadora de Trade In deverá estar previamente cadastrada na estrutura de banco e ERP do Microvix.

Importante ressaltar que essa é uma integração aonde o Microvix fara o resgate dos vouchers diretamente na Operadora de Trade In e todo o desenvolvimento e preparação desta estrutura deverá ser realizado pelo Terceiro e não terá nenhuma ação por parte da Linx, salvo o cadastro da nova operadora, caso necessário.


A integração de Vouchers Trade In foi desenvolvida com o propósito de validar um voucher gerado por uma operadora de Trade in e resgatar seus dados para que possa ser convertido em um Vale no Microvix, que posteriormente será utilizado como pagamento na aquisição do novo produto. 


IMPORTANTE!

Caso a operadora que será utilizada neste projeto não esteja previamente cadastrada no Microvix, deverá ser aberto um chamado para que seja efetuada a inclusão da nova operadora no HUB Trade In, conforme indicado abaixo:

 

  1. Inclusão operadora HUB:

    INSERT INTO mkt_parceiro (parceiro_nome, parceiro_contato, parceiro_email)
    VALUES (Informar nome operadora, informar contato parceiro, informar e-mail parceiro) INSERT INTO mkt_produto_parceiro (produto_id, parceiro_id, url_producao, url_producao_fail, url_homologacao, url_homologacao_fail)
    VALUES (informar ID produto, Informar ID parceiro, Informar URL produção, informar URL produção fail, informar URL homologação, Informar URL homologação fail)

  2. Inclusão operadora ERP (o id que será criado nessa tabela deverá ser igual ao id cadastrado na tabela do hub para que funcione corretamente a rotina):

    insert into tradein_parceiro
    (id_tradein_parceiro,nome_parceiro)
    values (valor do campo [PARCEIRO_ID] da tabela [dbo].[MKT_PARCEIRO] do hub
    , valor do campo [PARCEIRO_NOME] da tabela [dbo].[MKT_PARCEIRO] entre aspas)

A página de desenvolvimento desta customização pode ser acessada clicando aqui.


01 - CONSULTA VOUCHER

Chamada utilizada para buscar detalhes do voucher no momento do resgate do voucher no Microvix ERP.

Atenção!

Metodo: GET

EndPoint: /orders/<voucher>?api_key=<api_key>

  • Body sem corpo;
  • O cabeçalho Content-Type deve ser definido como application/json


Parâmetros incluídos na URL

Nome CampoDescriçãoTipagemObrigatório

voucher

Número do voucher gerado pela operadora

Integer

Sim

api_key

Chave de integração com a operadora

IntegerSim

Parâmetros de saída - JASON

CódigoDescriçãoConteúdo de ExemploObrigatório

id

Id do voucher da operadora (pode ser encontrado no voucher)

Integer

Sim

imei

O imei do telefone trocado

String

Sim

total

O total do pedido incluindo quaisquer promoções

Integer

Sim

date

A data em que o pedido foi gerado no formato iso8601

String

Sim

product.id

Id do produto da operadora

Integer

Sim

product.fullname

Nome completo do produto incluindo condição

String

Sim

store.id

Id da loja no sistema da operadora onde o pedido foi gerado

String

Sim

store.externalId

Id da loja no sistema da operadora onde o pedido foi gerado

Integer

Sim

store.name

Nome da loja

String

Sim

store.identificationType

Id da loja no sistema do parceiro onde o pedido foi gerado nome da loja

String

Sim

store.identificationNumber

O tipo de identificação legal da loja: Cnpj

String

Sim

cliente.name

O nome completo do cliente

String

Sim

cliente. identificationType

O tipo de identificação legal do cliente: cpf, cnpj

String

Sim

cliente. identificationNumber

O número de identificação legal do cliente

String

Sim

consumption.status

Se verdadeiro, o voucher foi consumido pelo cliente

Boolean

Sim

consumption.controlCode

Código de controle fornecido pelo parceiro no momento do consumo / nulo se não consumido

String

Sim

consumption.date

Data do consumo no formato iso8601 / null se não consumido

String

Sim

  • Exemplo

{

               "Id":"7672586",

               "imei":"451261591814266",

               "total":"200",

               "date":"2022-12-13T11:16:45.000Z",

               "product":{

                              "id":"303",

                              "fullName":"iPhone 5S 32GB Cinza Espacial (Defeituoso)"

               },

               "store":{

                              "id":"4",

                              "externalId":"TIM4",

                              "name":"Shopping Metro Santa Cruz",

                              "identificationType":"cnpj",

                              "identificationNumber":"04416818001384"

               },

               "client":{

                              "name":"Teste Cezar",

                              "identificationType":"cpf",

                              "identificationNumber":"60030860091"

               },

               "consumption":{

                              "status":"false",

                              "controlCode":null,

                              "date":null

               }

}

Respostas HTTP status code

CódigoDescrição

200

Sucesso

404

O pedido não foi encontrado para o parceiro autenticado

400

Solicitação inválida ocorreu um problema ao processar a solicitação. Verifique a seção códigos de erro. Possíveis códigos de erro: 120, 121, 401, 404.

02 - CONSULTA VOUCHERS POR CLIENTE

Esta chamada é utilizada para encontrar pedidos/vouchers gerados para um determinado cliente com base na identificação legal desse cliente

Atenção!

Metodo: GET

EndPoint: /orders/query?clienteidentificationNumber=<clienteidentificationNumber>?api_key=<api_key>

  • Body sem corpo;
  • O cabeçalho Content-Type deve ser definido como application/json


Parâmetros incluídos na URL

Nome CampoDescriçãoTipagemObrigatório

clientidentificationNumber

O número de identificação legal do cliente para encontrar vouchers para

String

Sim

api_key

Chave de integração com a operadora

Integer

Sim


Pontos de Atenção ao Desenvolvedor

A resposta é uma coleção de objetos de pedido conforme retornados pela chamada descrita anteriormente no método 01 deste manual.


Respostas HTTP status code

CódigoDescrição

200

Sucesso

404

O cliente não foi encontrado para o parceiro autenticado

400

Solicitação inválida ocorreu um problema ao processar a solicitação. Verifique a seção códigos de erro. Possíveis códigos de erro: 120, 121, 401, 404.

03 - CONSOME VOUCHERS

Esta chamada é utilizada para consumir um voucher

Atenção!

Metodo: POST

EndPoint: /orders/<voucher>/consume?api_key=<api_key>&validate_only

  • O cabeçalho Content-Type deve ser definido como application/json


Parâmetros incluídos na URL

Nome CampoDescriçãoTipagemObrigatório

voucher

Número do voucher gerado pela operadora

Integer

Sim

api_key

Chave de integração com a operadora

Integer

Sim

validate_only

Parâmetro pode ser passado no final da chamada. Caso seja passado o método apenas valida o consumo sem realizar efetivamente a operação

String

Não

Parâmetros de Entrada (Body) - JSON Content

Nome CampoDescriçãoTipagemObrigatório

total

Um inteiro com o total do pedido. Deve corresponder ao total do voucher para consumo. O total fornecido deve corresponder ao total encontrado no comprovante de compra gerado, caso contrário, o consumo vai falhar.

Integer

Sim

controlCode

Chave de integração com a operadora

String

Sim

storeIdentificationNumber

Uma string usada para identificar exclusivamente uma loja. Para o brasil, o cnpj será usado. Esse valor precisa ser fornecido sem hifens ou barras, apenas números. Deve corresponder ao que foi fornecido a operadora no processo de criação de lojas e logins. É recomendável que esse valor não venha das chamadas 01 e 02, pois isso anularia o finalidade de verificar novamente se o pedido é o pretendido para ser consumido.

Integer

Sim

clientIdentificationNumber

Uma string usada para identificar exclusivamente o cliente. Para o brasil, cpf ou cnpj será usado. Esse valor precisa ser fornecido sem hifens ou barras, apenas números. É recomendável que esse valor não venha das chamadas 01 e 02, pois isso anularia o finalidade de verificar novamente se o pedido é o pretendido para ser consumido.

String

Sim

Exemplo

{

            "total":310,

            "controlCode":"01234567890123456789",

            "storeIndentityNumber":"43708379009077",

            "clientIdentityNumber":"15747628771"

}


Respostas HTTP status code

CódigoDescrição

200

Se validate_only não foi especificado o voucher deve ser consumido. Se validate_only foi especificado o voucher poderá ser consumido, mas permanecerá em aberto.

404

O pedido não foi encontrado para o parceiro autenticado

400

Solicitação inválida ocorreu um problema ao processar a solicitação. Verifique a seção dos códigos de erro. Possíveis códigos de erro: 110, 111, 112, 113, 115, 116, 117, 401, 404.

04 - CANCELA VOUCHER

EEsta chamada é utilizada para cancelar um voucher

Atenção!

Metodo: POST

EndPoint: /orders/<voucher>/cancel?api_key=<api_key>&validate_only

  • O cabeçalho Content-Type deve ser definido como application/json


Parâmetros incluídos na URL

Nome CampoDescriçãoTipagemObrigatório

voucher

Número do voucher gerado pela operadora

Integer

Sim

api_key

Chave de integração com a operadora

Integer

Sim

validate_only

Parâmetro pode ser passado no final da chamada. Caso seja passado o método apenas valida o consumo sem realizar efetivamente a operação

String

Não

Parâmetros de Entrada (Body) - JSON Content

Nome CampoDescriçãoTipagemObrigatório

total

Um inteiro com o total do pedido. Deve corresponder ao total do voucher para consumo.

Integer

Sim

controlCode

Uma string livre de comprimento máximo de 20 caracteres. Deve ser enviado a mesma informação que foi enviada para o consumo do voucher.

String

Sim

storeIdentificationNumber

Uma string usada para identificar exclusivamente uma loja. Para o brasil, o cnpj será usado. Esse valor precisa ser fornecido sem hifens ou barras, apenas números. Deve corresponder ao que foi fornecido a operadora no processo de criação de lojas e logins. É recomendável que esse valor não venha das chamadas 01 e 02, pois isso anularia o finalidade de verificar novamente se o pedido é o pretendido.

Integer

Sim

clientIdentificationNumber

Uma string usada para identificar exclusivamente o cliente. Para o brasil, cpf ou cnpj será usado. Esse valor precisa ser fornecido sem hifens ou barras, apenas números. É recomendável que esse valor não venha das chamadas 01 e 02, pois isso anularia o finalidade de verificar novamente se o pedido é o pretendido.

String

Sim

Exemplo

{

            "total":310,

            "controlCode":"01234567890123456789",

            "storeIndentityNumber":"43708379009077",

            "clientIdentityNumber":"15747628771"

}


Respostas HTTP status code

CódigoDescrição

200

Se validate_only não foi especificado o voucher deve ser cancelado. Se validate_only foi especificado o voucher poderá ser consumido, mas permanecerá válido.

404

O pedido não foi encontrado para o parceiro autenticado

400

Solicitação inválida ocorreu um problema ao processar a solicitação. Verifique a seção dos códigos de erro. Possíveis códigos de erro: 110, 111, 112, 113, 115, 116, 117, 401, 404.

DESCRIÇÃO DOS CÓDIGOS DE ERRO

CódigoDescrição

110

Código de controle inválido. Verifique se você está fornecendo um controlcode válido no corpo json da solicitação. O Controlcode enviado no cancelamento deve ser o emos que foi enviado no consumo do voucher.

111

Total inválido ou ausente o total fornecido como parte do json do corpo da solicitação não corresponde ao total encontrado no Voucher.


112

Voucher já foi consumido. O voucher já foi consumido e não pode ser utilizado novamente. Não troque!

113

Id inválido ou malformado. Verifique se o id do pedido que você está fornecendo como parte da url é um número inteiro válido.

115

Tipo de conteúdo inválido ou incompatível. Verifique se você está fornecendo um cabeçalho content-type correto para a solicitação.

117

O pedido/voucher está em um estado inválido para a ação necessária. Verifique se, por exemplo, você não está tentando cancelar um voucher não consumido.

120

Número de identificação do cliente inválido ou ausente. Verifique se você está fornecendo um clientidentificationnumber correto no corpo json da solicitação.

121

Número de identificação da loja inválido ou ausente. Verifique se você está fornecendo um storeidentificationnumber correto no corpo json da solicitação. Pode ser que o número de identificação no sistema da operadora não coincida com o do parceiro. Nesse caso entre em contato com a equipe da operadora para atualizar este valor.


401

Não autorizado. Verifique se você está fornecendo uma chave de api correta como um parâmetro de consulta.

404

Não encontrado. O pedido identificado pelo id fornecido não foi encontrado. Isso pode ocorrer porque o id está incorreto, o pedido foi cancelado.

  • Sem rótulos