A integração de vales desenvolvida especificamente para ser utilizada em um único portal/CNPJ, possibilita a criação e exclusão de um vale diretamente na base da loja/CNPJ já caindo na base da loja como um vale compras ligado ao cliente. Esta integração está disponibilizada em uma API Publica (Padrão REST) validado no sistema Microvix.
O endereço para integração você pode acessar clicando aqui.
A página de desenvolvimento desta customização pode ser acessada clicando aqui.
Autenticação no header da requisição
| Campo | Descrição | Tipagem | Obrigatório |
|---|---|---|---|
| IntegrationAutentication | É a chave de integração usada no projeto do WebService de BD. Essa é uma chave gerada pelo time de BD para que os clientes possam utilizar o WebService com autenticação. Chave adquirida após contratação da integração. | Caractere | Sim |
Importante!
Esse header deve estar presente em todas as chamadas para os métodos.
Inserir um novo voucher – Requisição POST
Permite informar dados de adiamento para geração de um vale troca para o cliente ligado a uma empresa (CNPJ). Pode ser enviado mais de um adiantamento por cliente.
Atenção!
Link de método clicando aqui.
- Parâmetro de Entrada - Tipo JSON
| Nome Campo | Descrição | Tipagem | Obrigatório |
|---|---|---|---|
| NumeroControle | Número de controle do sistema integrador com máximo de 25 caracteres. Exemplo: 270112345678SVO | String | Sim |
| CnpjLoja | CNPJ da loja que está gerando o voucher, sem a pontuação, apenas números. | String | Sim |
| Motivo | Código que identifica o motivo da troca no Microvix. | Int | Sim |
| DocumentoCliente | CPF do cliente que utilizará o voucher, sem pontuação, apenas números. | String | Sim |
| Valor | Valor total do voucher | Decimal | Sim |
| Usuario | Código do usuário do Microvix para realizar o log da operação | Int | Sim |
| IdIntegracao | Identificador da integração com o sistema terceiro | Int | Sim |
| OrdemVenda | Número do pedido de venda no sistema terceiro | String | |
| DataIntegracaoLegado | Data que o documento foi incluído no sistema legado | DateTime | Sim |
| Status | Caso informe o campo, enviar o valor 1 | Int | Sim |
- Retornos
| Código | Descrição | Conteúdo de Exemplo |
|---|---|---|
| 200 | Indica que a operação foi processada com sucesso. Será enviado um objeto JSON com o campo “Status” tendo a mensagem com o resultado da operação. | {"Status": "Vale inserido com sucesso!"} |
| 401 | Indica que o header IntegrationAutentication não é valido ou não foi fornecido | {"Message": "Authorization has been denied for this request."} |
| 400 | Indica que existe alguma inconsistência nos dados da requisição e uma lista de erros será retornada com cada erro encontrado. | [ "O motivo não foi informado.", "O documento do cliente não foi informado." ] |
Cancelar um voucher – Requisição POST
Permite informar o número de controle para cancelar um vale ativo. Apenas vales ativos podem ser cancelados. Se o vale já estiver resgatado ou cancelado será retornado mensagem de erro correspondente.
Atenção!
Link de método clicando aqui.
- Parâmetro de Entrada - Tipo JSON
| Nome Campo | Descrição | Tipagem | Obrigatório |
|---|---|---|---|
| NumeroControle | Número de controle do sistema integrador com máximo de 25 caracteres. Exemplo: 270112345678SVO | String | Sim |
- Retornos
| Código | Descrição | Conteúdo de Exemplo |
|---|---|---|
| 200 | Indica que a operação foi processada com sucesso. Será enviado um objeto JSON com o campo “Status” tendo a mensagem com o resultado da operação. | {"Status": "Vale cancelado com sucesso!"} |
| 401 | Indica que o header IntegrationAutentication não é valido ou não foi fornecido | {"Message": "Authorization has been denied for this request."} |
| 400 | Indica que existe alguma inconsistência nos dados da requisição e uma lista de erros será retornada com cada erro encontrado. | [ "O número de controle não foi informado.", "Não existe um vale cadastrado com o número de controle informado." ] |
Pontos de Atenção ao Desenvolvedor
• A string JSON deve seguir com caracteres no padrão UTF-8
• Adicionar o Header “Content-Type” com valor “application/json” nas requisições
• Os nomes dos campos devem estar entre aspas conforme padrão JSON
• Os valores String devem estar entre aspas duplas
• Os valores DateTime devem seguir o padrão ISO-8601 do JSON entre aspas duplas
• Os valores Integer devem ser compostos apenas por números sem pontuação e sem aspas
• Os valores Decimal devem conter apenas números e o caractere ‘.’ (ponto) como separador decimal.