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.
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 Campo | Descrição | Tipagem | Obrigatório |
---|---|---|---|
voucher | Número do voucher gerado pela operadora | Integer | Sim |
api_key | Chave de integração com a operadora | Integer | Sim |
Parâmetros de saída - JASON
Código | Descrição | Conteúdo de Exemplo | Obrigató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 |
Id do produto da operadora | Integer | Sim | |
product.fullname | Nome completo do produto incluindo condição | String | Sim |
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 |
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 |
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ódigo | Descriçã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 Campo | Descrição | Tipagem | Obrigató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ódigo | Descriçã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 Campo | Descrição | Tipagem | Obrigató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 Campo | Descrição | Tipagem | Obrigató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ódigo | Descriçã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 Campo | Descrição | Tipagem | Obrigató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 Campo | Descrição | Tipagem | Obrigató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ódigo | Descriçã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ódigo | Descriçã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. |