API de Integração - devbasetecnologia/devmobility GitHub Wiki

API de Integração

Este é o manual para que você possa integrar sua empresa à Plataforma Digital da DevBase.

Sugerimos que este documento seja lido com atenção, e usado como guia de referência para quaisquer dúvidas não somente no momento da implementação da integração de sua plataforma com a API da DevBase, mas para quaisquer mudanças nos sistemas.

O conteúdo deste Manual de Integração se destina a programadores e desenvolvedores de plataformas de mobilidade urbana e/ou entregas que desejam realizar a criação de solicitações por integração via API no sistemas da família DevMobility e DevEntregas.

Neste documento o desenvolvedor/analista terá acesso a todos os passos e processos referentes à integração via as funcionalidades da API.

Sugerimos também que, periodicamente e sempre que for iniciar um desenvolvimento relacionado à criação de solicitações, utilize este portal para acompanhamento de mudanças e versionamento dos produtos de nossa plataforma.

Autenticação da WebApi

Todo consumo da webapi deve ser realizado acompanhando do envio das credenciais de autenticação. O sistema de autenticação utilizado é o Basic Authentication (Basic Auth), e deve ser feito em uma requisição segura HTTPS (TLS 1.2).

Obtenção de chaves de autenticação

Suas credencias de autenticação para o ambiente de produção devem ser solicitadas diretamente para o administrador da plataforma.

Obtenção de parâmetros internos

  • "ServicoItemID": ID do Serviço por região (solicitar ao administrador da plataforma);
  • "TipoPagamentoID": ID da forma de pagamento (solicitar ao administrador da plataforma);
  • "CategoriaMercadoriaID" (Somente para solicitação de entregas): ID da categoria de mercadoria (solicitar ao administrador da plataforma);

Calcular Valores de Solicitação de Viagem

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/CalcularValoresViagem Método: POST

Ex. de consumo:

Header:

POST /api/External/CalcularValoresViagem HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic aHDCQHNlVXNyVDV0OkcqT1U2czQwOCYldXNrMHMkIypnY2xqZg==
Content-Type: application/json
Cookie: ARRAffinity=0de3dfe0f956df48d150a3cc8506c1efae6a5e5a5e673891639f0556803020f3

JSON de requisição:

{
    "ClienteID":"1",
    "EnderecoOrigem":"R. Tv. 1, 61 - Leblon, Catalão - GO, Brasil",
    "ListaDestinoCidade":[
    {
                "Latitude": "-18.164714",
                "Longitude": "-47.94141800000001"
    }]
}

ParamCalculoValores

Propriedade Tipo Tamanho Obrigatório Descrição
ServicoItemID Inteiro Não O código do serviço desejado (opcional, se não informado, serão listados todos os serviços disponíveis.
ClienteID Inteiro Sim * Obrigatório para acessos de empresa (* Não é necessário informar esse campo se o cadastro de integração for de cliente) .
Latitude Texto 20 Não Latitude do endereço. ¹
Longitude Texto 20 Não Longitude do endereço. ¹
EnderecoOrigem Texto 300 Sim
ListaDestinoCidade List<EnderecoDestino> Sim Lista de destinos. Obrigatória a informação de ao menos 1 destino, exceto quando o sistema estiver com a funcionalidade PermiteInformarDestinoDepois habilitada; neste caso, a lista pode ser enviada vazia.

¹ Se latitude/longitude não forem informadas, serão definidas automaticamente com base nas informações do endereço.

EnderecoDestino

Propriedade Tipo Tamanho Obrigatório Descrição Propriedade
Endereco Texto 300 Sim Logradouro com número.
Latitude Texto 20 Não Latitude do endereço. ¹
Longitude Texto 20 Não Longitude do endereço. ¹

¹ Se latitude/longitude não forem informadas, serão definidas automaticamente com base nas informações do endereço.

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "RetornoCalculoValores": {
        "Latitude": "-18.1498",
        "Longitude": "-47.93871",
        "EnderecoOrigem": "Travessa Um, Residencial Leblon, Catalão - GO, 75703-490, Brasil",
        "ListaDestinoCidade": [
            {
                "Endereco": "Rua João Boaventura, 217, São João, Catalão - GO, 75703-260, Brasil",
                "Peso": null,
                "AlturaCM": null,
                "LarguraCM": null,
                "ComprimentoCM": null,
                "Latitude": "-18.16493",
                "Longitude": "-47.9415"
            }
        ],
        "ListaServicoValor": [
            {
                "ServicoItemID": 1,
                "ServicoNome": "X",
                "Valor": 7.99
            }
        ]
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "message": "Endereço de origem não econtrado. Por favor, informe um endereço de origem válido."
}

Calcular Valores de Solicitação de Entrega

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/CalcularValoresEntrega Método: POST

Ex. de consumo:

Header:

POST /api/External/CalcularValoresEntrega HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic aHDCQHNlVXNyVDV0OkcqT1U2czQwOCYldXNrMHMkIypnY2xqZg==
Content-Type: application/json
Cookie: ARRAffinity=0de3dfe0f956df48d150a3cc8506c1efae6a5e5a5e673891639f0556803020f3

JSON de requisição:

{
    "ClienteID":"1",
    "ServicoItemID":"201",
    "EnderecoOrigem":"R. Tv. 1, 61 - Leblon, Catalão - GO, Brasil",
    "AgrupamentoVeiculoID":"2",
    "ListaDestinoCidade":[
    {
        "Endereco": "Rua João Boaventura, 217, São João, Catalão - GO, 75703-260, Brasil",
        "Peso":"1",
        "AlturaCM":"1",
        "LarguraCM":"1",
        "ComprimentoCM":"1"
    }]
}

ParamCalculoValores

Propriedade Tipo Tamanho Obrigatório Descrição
ClienteID Inteiro Sim * Obrigatório para acessos de empresa (* Não é necessário informar esse campo se o cadastro de integração for de cliente).
ServicoItemID Inteiro Não O código do serviço desejado (opcional, se não informado, serão listados todos os serviços disponíveis).
AgrupamentoVeiculoID Inteiro Sim O código do agrupamento de veículos.
Latitude Texto 20 Não Latitude do endereço. ¹
Longitude Texto 20 Não Longitude do endereço. ¹
EnderecoOrigem Texto 300 Sim
ListaDestinoCidade List<EnderecoDestino> Sim Lista de destinos. Obrigatória a informação de ao menos 1 destino.

¹ Se latitude/longitude não forem informadas, serão definidas automaticamente com base nas informações do endereço.

EnderecoDestino

Propriedade Tipo Tamanho Obrigatório Descrição Propriedade
Endereco Texto 300 Sim Logradouro com número.
Latitude Texto 20 Não Latitude do endereço. ¹
Longitude Texto 20 Não Longitude do endereço. ¹
Peso Decimal 15,3 Sim Peso da mercadoria
AlturaCM Inteiro Sim ² Altura da mercadoria
LarguraCM Inteiro Sim ² Largura da mercadoria
ComprimentoCM Inteiro Sim ² Comprimento da mercadoria

¹ Se latitude/longitude não forem informadas, serão definidas automaticamente com base nas informações do endereço.

² Obrigatórios caso o serviço esteja parametrizado para exigir informação das medidas.

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "RetornoCalculoValores": {
        "Latitude": "-18.1498",
        "Longitude": "-47.93871",
        "EnderecoOrigem": "Travessa Um, Residencial Leblon, Catalão - GO, 75703-490, Brasil",
        "ListaDestinoCidade": [
            {
                "Endereco": "Rua João Boaventura, 217, São João, Catalão - GO, 75703-260, Brasil",
                "Peso": 1.0,
                "AlturaCM": null,
                "LarguraCM": null,
                "ComprimentoCM": null,
                "Latitude": "-18.16483",
                "Longitude": "-47.94152"
            }
        ],
        "ListaServicoValor": [
            {
                "ServicoItemID": 201,
                "ServicoNome": "Entrega Agora",
                "Valor": 24.67
            }
        ]
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "message": "Veículos não compatíveis com a carga definida. Por favor verifique os volumes (tamanho/peso/quantidade) e tente novamente."
}

Criação de Solicitação de Viagem

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/CriarSolicitacaoViagem Método: POST

Ex. de consumo:

Header:

POST /api/External/CriarSolicitacaoViagem HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic aHDCQHNlVXNyVDV0OkcqT1U2czQwOCYldXNrMHMkIypnY2xqZg==
Content-Type: application/json
Cookie: ARRAffinity=0de3dfe0f956df48d150a3cc8506c1efae6a5e5a5e673891639f0556803020f3

JSON de requisição:

{
    "ClienteID": 3,
    "ServicoItemID": 5,
    "TipoPagamentoID": 4,
    "Valor": 12.54,
    "enderecoOrigem": {
        "Endereco": "Rua da Padroeira, 200 - Centro",
        "CEP": "13218230",
        "Cidade": "Jundiaí ",
        "EstadoSigla": "SP",
        "Observacao": "Próximo à padaria"
    },
    "lstDestino": [
        {
            "Endereco": "R. Euclídes da Cunha, 70 - Centro, Jundiaí - SP, 13201-833",
            "CEP": "13201-833",
            "Cidade": "Jundiaí",
            "EstadoSigla": "SP",
            "Observacao": "PA Unimed"
        },
        {
            "Endereco": "R. Onze de Junho, 169 - Centro",
            "CEP": "13201-038",
            "Cidade": "Jundiaí",
            "EstadoSigla": "SP"
        }
    ]
}

Solicitacao

Propriedade Tipo Tamanho Obrigatório Descrição
ServicoItemID Inteiro Sim O código do serviço desejado.
ClienteID Inteiro Sim * Obrigatório para acessos de empresa (* Não é necessário informar esse campo se o cadastro de integração for de cliente) .
enderecoOrigem EnderecoSolicitacao Sim
lstDestino List<EnderecoSolicitacao> Sim Lista de destinos. Obrigatória a informação de ao menos 1 destino, exceto quando o sistema estiver com a funcionalidade PermiteInformarDestinoDepois habilitada; neste caso, a lista pode ser enviada vazia.
DataHoraAgendamento Datahora Não Data/hora para agendamento da solicitação. Opcional. Se não informado, a solicitação será executada imediatamente.
Valor Decimal 15,2 Não Se o campo "Valor" não for informado, será calculado automaticamente pelo sistema com base nos parâmetros de preço do serviço.
TipoPagamentoID Inteiro Sim ID do tipo de pagamento.

EnderecoSolicitacao

Propriedade Tipo Tamanho Obrigatório Descrição Propriedade
CEP Texto 9 Sim CEP do endereço.
Endereco Texto 300 Sim Logradouro com número.
Cidade Texto 100 Sim Cidade do endereço.
EstadoSigla Texto 100 Sim Sigla do estado (SP, RJ, MG, etc)
Latitude Texto 20 Não Latitude do endereço. ¹
Longitude Texto 20 Não Longitude do endereço. ¹
Observacao Texto 300 Não

¹ Se latitude/longitude não forem informadas, serão definidas automaticamente com base nas informações do endereço.

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Solicitação criada com sucesso.",
        "resultado": {
            "SolicitacaoID": 2086,
            "DataHoraCriacao": "2020-05-22T18:33:24.1178131"
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 131,
            "mensagemErro": "enderecoOrigem não pode ser nulo."
        }
    }
}

Criação de Solicitação de Entrega

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/CriarSolicitacaoEntrega Método: POST

Ex. de consumo:

Header:

POST /api/External/CriarSolicitacaoEntrega HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic aHDCQHNlVXNyVDV0OkcqT1U2czQwOCYldXNrMHMkIypnY2xqZg==
Content-Type: application/json
Cookie: ARRAffinity=0de3dfe0f956df48d150a3cc8506c1efae6a5e5a5e673891639f0556803020f3

JSON de requisição:

{
    "ClienteID": 10,
    "ServicoItemID": 201,
    "TipoPagamentoID": 25,
    "Valor": 16.14,
    "enderecoOrigem": {
        "Endereco": "Rua do Rosário, 100 - Centro",
        "CEP": "13218230",
        "Cidade": "Jundiaí ",
        "EstadoSigla": "SP",
        "Observacao": "Portão cinza",
        "NomeContato": "João",
        "CelularContato": "11937732528",
        "EmailContato": "[email protected]"
    },
    "lstDestino": [
        {
            "Endereco": "Avenida Antônio Frederico Ozanan, 6000, Vila Rio Branco",
            "CEP": "13215900",
            "Cidade": "Jundiaí",
            "EstadoSigla": "SP",
            "Observacao": "Casa dos fundos",
            "NomeContato": "José",
            "CelularContato": "11937362598",
            "EmailContato": "[email protected]",
            "lstMercadoria": [
                {
                    "CategoriaMercadoriaID": 1,
                    "Quantidade": 1,
                    "Peso": 1.35,
                    "Valor": 1200.35,
                    "Altura": 65,
                    "Largura": 112,
                    "Comprimento": 15,
                    "Descricao": "Televisão"
                }
            ]
        },
        {
            "Endereco": "Rua Coronel Boaventura Mendes Pereira, 45 - Vila Boaventura",
            "CEP": "13201-801",
            "Cidade": "Jundiaí",
            "EstadoSigla": "SP",
            "lstMercadoria": [
                {
                    "CategoriaMercadoriaID": 1,
                    "Quantidade": 1,
                    "Peso": 0.45,
                    "Valor": 750.99,
                    "Altura": 20,
                    "Largura": 10,
                    "Comprimento": 1,
                    "Descricao": "Celular"
                },
                {
                    "CategoriaMercadoriaID": 2,
                    "Quantidade": 2,
                    "Peso": 0.312,
                    "Valor": 35,
                    "Altura": 2,
                    "Largura": 2,
                    "Comprimento": 20,
                    "Descricao": "Cabos"
                }
            ]
        }
    ]
}

Solicitacao

Propriedade Tipo Tamanho Obrigatório Descrição
ServicoItemID Inteiro Sim O código do serviço desejado.
ClienteID Inteiro Sim * Obrigatório para acessos de empresa (* Não é necessário informar esse campo se o cadastro de integração for de cliente) .
enderecoOrigem EnderecoSolicitacao Sim
lstDestino List<EnderecoSolicitacao> Sim Lista de destinos. Obrigatória a informação de ao menos 1 destino.
DataHoraAgendamento Datahora Não Data/hora para agendamento da solicitação. Opcional. Se não informado, a solicitação será executada imediatamente.
Valor Decimal 15,2 Não Se o campo "Valor" não for informado, será calculado automaticamente pelo sistema com base nos parâmetros de preço do serviço.
TipoPagamentoID Inteiro Sim ID do tipo de pagamento.

EnderecoSolicitacao

Propriedade Tipo Tamanho Obrigatório Descrição Propriedade
CEP Texto 9 Sim CEP do endereço.
Endereco Texto 300 Sim Logradouro com número.
Cidade Texto 100 Sim Cidade do endereço.
EstadoSigla Texto 100 Sim Sigla do estado (SP, RJ, MG, etc)
Latitude Texto 20 Não Latitude do endereço. ¹
Longitude Texto 20 Não Longitude do endereço. ¹
Observacao Texto 300 Não
NomeContato Texto 150 Não
EmailContato Texto 100 Não
CelularContato Texto 20 Não
lstMercadoria List<Mercadoria> Sim * Obrigatoriedade definida de acordo com a parametrização do Serviço. Se não obrigatório, será desconsiderado.

¹ Se latitude/longitude não forem informadas, serão definidas automaticamente com base nas informações do endereço.

Mercadoria

Propriedade Tipo Tamanho Obrigatório Descrição
Descricao Texto 150 Sim Descrição da mercadoria.
Altura Inteiro Sim ¹ Altura da mercadoria
Largura Inteiro Sim ¹ Largura da mercadoria
Comprimento Inteiro Sim ¹ Comprimento da mercadoria
Quantidade Inteiro Sim Quantidade de itens.
Peso Decimal 15,3 Sim Peso da mercadoria
Valor Decimal 15,2 Sim Valor da mercadoria.
CategoriaMercadoriaID Inteiro Sim ID da categoria de mercadoria.

¹ Obrigatórios caso o serviço esteja parametrizado para exigir informação das medidas.

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Solicitação criada com sucesso.",
        "resultado": {
            "SolicitacaoID": 2087,
            "DataHoraCriacao": "2020-05-22T18:36:48.1178131"
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 102,
            "mensagemErro": "lstMercadoria - ServicoItemID exige que sejam informadas as medidas (Altura, Largura e Comprimento) das mercadorias."
        }
    }
}

Cancelar Solicitação

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/CancelarSolicitacao?solicitacaoID={id}&tipo={string}&cancEngano={boolean}&cliNaoEncontrado={boolean} Método: POST

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
solicitacaoID Inteiro Sim
tipo String 1 Sim Indica se o cancelamento foi por iniciativa do Cliente ("C") ou do prestador ("P"). Valores aceitos: "C" ou "P".
cancEngano Boolean Não Indica se o cancelamento foi feito devido ao aceite da solicitação por engano. Considerado apenas em cancelamentos por iniciativa do prestador. Default: false.
cliNaoEncontrado Boolean Não Indica se o cancelamento foi feito devido ao cliente não ter sido encontrado no endereço informado. Considerado apenas em cancelamentos por iniciativa do prestador.Default: false.

Ex. de consumo:

Header:

POST /api/External/CancelarSolicitacao?solicitacaoID=4&tipo=P&cancEngano=false&cliNaoEncontrado=true HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic aHDCQHNlVXNyVDV0OkcqT1U2czQwOCYldXNrMHMkIypnY2xqZg==
Content-Type: application/json
Cookie: ARRAffinity=0de3dfe0f956df48d150a3cc8506c1efae6a5e5a5e673891639f0556803020f3

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "message": "OK"
}

Ex. de outros retornos:

Status: 404 Not Found

{
    "message": "Solicitação não encontrada"
}

Consultar Status da Solicitação

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/SolicitacaoStatus?solicitacaoID={id} Método: GET

Ex. de consumo:

Header:

GET /api/External/SolicitacaoStatus?solicitacaoID=67563 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "SolicitacaoStatus": {
        "SolicitacaoID": 10,
        "TipoSolicitacaoID": 4,
        "TipoSolicitacaoDesc": "Entrega",
        "StatusSolicitacaoID": 4,
        "StatusSolicitacaoDesc": "Solicitação Finalizada"
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Message": "The request is invalid.",
    "MessageDetail": "The parameters dictionary contains a null entry for parameter 'solicitacaoID' of non-nullable type 'System.Int64' for method 'System.Net.Http.HttpResponseMessage GetSolicitacaoStatus(Int64)' in 'WebApi.Controllers.ExternalController'. An optional parameter must be a reference type, a nullable type, or be declared as an optional parameter."
}

Consultar Agrupamentos de Veículo

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/AgrupamentoVeiculo Método: GET

Ex. de consumo:

Header:

GET /api/External/AgrupamentoVeiculo HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "AgrupamentoVeiculo": [
        {
            "AgrupamentoVeiculoID": 1,
            "AgrupamentoVeiculoDesc": "Moto",
            "ImagemAgrupamento": "https://sacluber.blob.core.windows.net/imagens/moto-de-entrega-preto.png",
            "Ativo": true,
            "Mensagem": "Entrega Expressa (mesmo dia). Pequenos volumes de até 40 x 30 x 30 cm e 20 kg.",
            "InformaMedidas": false,
            "InformaPeso": false,
            "FatorCubagem": 300,
            "InformaProdutos": false,
            "ProdutoUnico": false
        },
        {
            "AgrupamentoVeiculoID": 2,
            "AgrupamentoVeiculoDesc": "Cargas",
            "ImagemAgrupamento": "https://sacluber.blob.core.windows.net/imagens/truck-preto.png",
            "Ativo": true,
            "Mensagem": "Entregas de cargas e pacotes de maior volume/dimensão. Serviços de entrega no mesmo dia, ou dia seguinte (consultar disponibilidade na cidade de origem).",
            "InformaMedidas": true,
            "InformaPeso": true,
            "FatorCubagem": 300,
            "InformaProdutos": true,
            "ProdutoUnico": false
        }
    ]
}

Ex. de retorno com erro:

Status: 401 Unauthorized

{
    "error": {
        "code": 401,
        "message": "Não Autorizado: Acesso negado devido a credenciais inválidas."
    }
}

Consultar Formas de Pagamento

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/FormaPagamento?clienteID={id}&servicoItemID={id}&valor={decimal} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
clienteID Inteiro Sim
servicoItemID Inteiro Não Se informado, lista as formas de pagamento disponíveis para o serviço específico. Se não informado, lista todas as formas de pagamento de todos os serviços.
valor Decimal 15,2 Não Se informado, só lista a forma de pagamento Saldo em Carteira comportar o valor (i.e., se o valor do saldo for igual ou superior o valor informado).

Ex. de consumo:

Header:

GET /api/External/FormaPagamento?clienteID=314&servicoItemID=213&valor=10.23 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "FormaPagamento": [
        {
            "BandeiraCartaoImg": null,
            "objCartaoCredito": null,
            "TipoPagamentoID": 4,
            "TipoPagamentoDesc": "Maquina de Cartão",
            "Ativo": false,
            "DependePrestador": false,
            "TaxaFixa": null,
            "TaxaPorcentagem": null,
            "PossePagamento": 2,
            "Viagem": false,
            "Entrega": false,
            "ReceberColetaOuEntrega": null,
            "CalcularRetorno": false
        },
        {
            "BandeiraCartaoImg": null,
            "objCartaoCredito": null,
            "TipoPagamentoID": 5,
            "TipoPagamentoDesc": "Dinheiro",
            "Ativo": false,
            "DependePrestador": false,
            "TaxaFixa": null,
            "TaxaPorcentagem": null,
            "PossePagamento": 2,
            "Viagem": false,
            "Entrega": false,
            "ReceberColetaOuEntrega": null,
            "CalcularRetorno": true
        },
        {
            "BandeiraCartaoImg": null,
            "objCartaoCredito": null,
            "TipoPagamentoID": 25,
            "TipoPagamentoDesc": "Boleto",
            "Ativo": false,
            "DependePrestador": false,
            "TaxaFixa": null,
            "TaxaPorcentagem": null,
            "PossePagamento": 3,
            "Viagem": false,
            "Entrega": false,
            "ReceberColetaOuEntrega": null,
            "CalcularRetorno": false
        },
        {
            "BandeiraCartaoImg": null,
            "objCartaoCredito": null,
            "TipoPagamentoID": 26,
            "TipoPagamentoDesc": "Transferência",
            "Ativo": false,
            "DependePrestador": false,
            "TaxaFixa": null,
            "TaxaPorcentagem": null,
            "PossePagamento": 3,
            "Viagem": false,
            "Entrega": false,
            "ReceberColetaOuEntrega": null,
            "CalcularRetorno": false
        },
        {
            "BandeiraCartaoImg": null,
            "objCartaoCredito": null,
            "TipoPagamentoID": 27,
            "TipoPagamentoDesc": "Maquina de Cartão (pagamento na coleta)",
            "Ativo": false,
            "DependePrestador": false,
            "TaxaFixa": null,
            "TaxaPorcentagem": null,
            "PossePagamento": 2,
            "Viagem": false,
            "Entrega": false,
            "ReceberColetaOuEntrega": null,
            "CalcularRetorno": true
        },
        {
            "BandeiraCartaoImg": null,
            "objCartaoCredito": null,
            "TipoPagamentoID": 29,
            "TipoPagamentoDesc": "Faturado (sem retorno)",
            "Ativo": false,
            "DependePrestador": false,
            "TaxaFixa": null,
            "TaxaPorcentagem": null,
            "PossePagamento": 3,
            "Viagem": false,
            "Entrega": false,
            "ReceberColetaOuEntrega": null,
            "CalcularRetorno": false
        },
        {
            "BandeiraCartaoImg": null,
            "objCartaoCredito": null,
            "TipoPagamentoID": 30,
            "TipoPagamentoDesc": "Faturado (com retorno)",
            "Ativo": false,
            "DependePrestador": false,
            "TaxaFixa": null,
            "TaxaPorcentagem": null,
            "PossePagamento": 3,
            "Viagem": false,
            "Entrega": false,
            "ReceberColetaOuEntrega": null,
            "CalcularRetorno": true
        }
    ]
}

Ex. de retorno com erro:

Status: 401 Unauthorized

{
    "error": {
        "code": 401,
        "message": "Não Autorizado: Acesso negado devido a credenciais inválidas."
    }
}

Consultar Forma de Pagamento por ServicoItem

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/PagamentoPorServicoItem?tipoPagamentoID={id}&servicoItemID={id}&valor={decimal} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
tipoPagamentoID Inteiro Sim
servicoItemID Inteiro Não Se informado, só retorna os detalhes da forma de pagamento se ela estiver ativa para o servicoItem informado. Caso contrário, lista os detalhes se a forma de pagamento estiver aprovada para pelo menos um serviço.
valor Decimal 15,2 Não Se informado, só lista a forma de pagamento Saldo em Carteira comportar o valor (i.e., se o valor do saldo for igual ou superior o valor informado).

Ex. de consumo:

Header:

GET /api/External/PagamentoPorServicoItem?tipoPagamentoID=4&servicoItemID=213&valor=10.23 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "TipoPagamento": {
        "RecargaAtiva": true,
        "TipoPagamentoID": 4,
        "TipoPagamentoDesc": "Maquina de Cartão",
        "Ativo": true,
        "DependePrestador": true,
        "TaxaFixa": 0.00,
        "TaxaPorcentagem": null,
        "PossePagamento": null,
        "Viagem": true,
        "Entrega": true,
        "ReceberColetaOuEntrega": "E",
        "CalcularRetorno": false
    }
}

Ex. de retorno com erro:

Status: 401 Unauthorized

{
    "error": {
        "code": 401,
        "message": "Não Autorizado: Acesso negado devido a credenciais inválidas."
    }
}

Consultar Forma de Pagamento por Serviço e Região

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/PagamentoPorServicoERegiao?tipoPagamentoID={id}&servicoID={id}&regiaoID={id}&clienteID={id} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
tipoPagamentoID Inteiro Sim
servicoID Inteiro Não Se informado, só retorna os detalhes da forma de pagamento se ela estiver ativa para o serviço informado. Caso contrário, lista os detalhes se a forma de pagamento estiver aprovada para pelo menos um serviço.
regiaoID Inteiro Não Se informado, só retorna os detalhes da forma de pagamento se ela estiver ativa para a região informada. Caso contrário, lista os detalhes se a forma de pagamento estiver aprovada em pelo menos uma região.
clienteID Inteiro Não Se informado, só retorna os detalhes da forma de pagamento se ela estiver disponível para o cliente informado. Caso contrário, lista os detalhes se a forma de pagamento estiver disponível para pelo menos um cliente.

Ex. de consumo:

Header:

GET /api/External/PagamentoPorServicoERegiao?tipoPagamentoID=4&servicoID=1&regiaoID=1&clienteID=314 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "TipoPagamento": {
        "RecargaAtiva": true,
        "TipoPagamentoID": 4,
        "TipoPagamentoDesc": "Maquina de Cartão",
        "Ativo": true,
        "DependePrestador": true,
        "TaxaFixa": 0.00,
        "TaxaPorcentagem": null,
        "PossePagamento": null,
        "Viagem": true,
        "Entrega": true,
        "ReceberColetaOuEntrega": "E",
        "CalcularRetorno": false
    }
}

Ex. de retorno com erro:

Status: 401 Unauthorized

{
    "error": {
        "code": 401,
        "message": "Não Autorizado: Acesso negado devido a credenciais inválidas."
    }
}

Consultar Cliente

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/Cliente?documento={documento}&telefone={telefone} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
documento String Não
telefone String Não

Ex. de consumo:

Header:

GET /api/External/Cliente?telefone=19997298312 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Cliente",
        "resultado": {
            "ClienteID": 311,
            "ClienteNome": "Cliente Teste 311",
            "Documento": "36677705889",
            "DataCadastro": "2022-01-03T22:56:14.3",
            "Email": "[email protected]",
            "Status": "Ativo",
            "Plataforma": "Android",
            "Genero": "Masculino",
            "Versao": "b193-v5.1.2",
            "Saldo": 0.00
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 121,
            "mensagemErro": "ClienteID informado não foi encontrado no cadastro."
        }
    }
}

Consultar Prestador

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/Prestador?documento={documento}&telefone={telefone} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
documento String Não
telefone String Não

Ex. de consumo:

Header:

GET /api/External/Prestador?documento=49492128004 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Prestador",
        "resultado": {
            "PrestadorID": 311,
            "PrestadorNome": "Prestador Teste 311",
            "Documento": "36677705889",
            "DataCadastro": "2022-01-03T22:56:14.3",
            "Email": "[email protected]",
            "Status": "Ativo",
            "Plataforma": "Android",
            "Genero": "Masculino",
            "Versao": "b193-v5.1.2",
            "Saldo": 0.00
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 121,
            "mensagemErro": "PrestadorID informado não foi encontrado no cadastro."
        }
    }
}

Cadastrar Pré-Cliente

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/CadastrarPreCliente?clienteNome={clienteNome}&celular={celular} Método: POST

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
clienteNome String Sim
celular String Sim

Ex. de consumo:

Header:

POST /api/External/CadastrarPreCliente?clienteNome=Cliente Teste&celular=19997298312 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "gravado com sucesso!",
        "resultado": {
            "ClienteID": 311,
            "ClienteNome": "Cliente Teste"
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Ocorreu um problema para gravar.",
        "resultado": null
    }
}

Excluir Vínculo do Cliente Com a Empresa

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/RemoverVinculoEmpresa?clienteID={clienteID} Método: POST

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
clienteID Integer Sim

Ex. de consumo:

Header:

POST /api/External/RemoverVinculoEmpresa?clienteID=392 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Vinculo removido com sucesso!",
        "resultado": null
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 122,
            "mensagemErro": "ClienteID informado não está vinculado à empresa."
        }
    }
}

Status Localização

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/StatusLocalizacao?solicitacaoID={solicitacaoID} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
solicitacaoID Integer Sim

Ex. de consumo:

Header:

GET /api/External/StatusLocalizacao?solicitacaoID=4102 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Última Localização",
        "resultado": {
            "Latitude": "-22.9948747",
            "Longitude": "-47.505513"
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
     "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 161,
            "mensagemErro": "SolicitacaoID informado não pertence à empresa."
        }
    }
}

Status Solicitação por Etapas

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/EtapaSolicitacao?solicitacaoID={solicitacaoID} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
solicitacaoID Integer Sim

Endpoint para consulta aos dados da solicitação em andamento.

model de retorno:

public class EtapaSolicitacao
{
    int Etapa;
    string StatusSolicitacao;
    string NomePrestador;
    string Veiculo;
    string Cor;
    string Placa;
    string PrevisaoChegadaOrigem;
    DateTime DataHoraChegouOrigem;
    string PrevisaoChegadaDestino;
    bool ViagemFinalizada;
    bool ViagemFinalizada;
    decimal? DistanciaTotal;
}

Ex. de consumo:

Header:

GET /api/External/EtapaSolicitacao?solicitacaoID=4102 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "EtapaSolicitacao": {
        "Etapa": 2,
        "StatusSolicitacao": "Seu motorista já está a caminho.",
        "NomePrestador": "Ester Cilene Da Silva Fagundes",
        "Veiculo": "VW - Gol",
        "Cor": "Cinza",
        "Placa": "ITU0E68",
        "PrevisaoChegadaOrigem": "2 minutos",
        "DataHoraChegouOrigem": null,
        "PrevisaoChegadaDestino": "",
        "ViagemFinalizada": false,
        "DistanciaTotal": null
    }
}

Outros exemplos dos possíveis retornos deste método:

1 - localizando motorista:

Etapa - 1
StatusSolicitacao - "Localizando motorista."
NomePrestador - null
Veiculo - null
Cor - null
Placa - null
PrevisaoChegadaOrigem - null
DataHoraChegouOrigem - null
PrevisaoChegadaDestino - null
ViagemFinalizada - false
DistanciaTotal - null

2 - aceitou:

Etapa - 2
StatusSolicitacao - "Seu motorista já está a caminho."
NomePrestador - "João"
Veiculo - "Celta"
Cor - "Vermelho"
Placa - "DNU5060"
PrevisaoChegadaOrigem - "5 minutos"
DataHoraChegouOrigem - null
PrevisaoChegadaDestino - null
ViagemFinalizada - false
DistanciaTotal - null

3 - chegou origem:

Etapa - 3
StatusSolicitacao - "O motorista chegou ao local de embarque."
NomePrestador - "João"
Veiculo - "Celta"
Cor - "Vermelho"
Placa - "DNU5060"
PrevisaoChegadaOrigem - null
DataHoraChegouOrigem - 15/09/2021 12:05:00
PrevisaoChegadaDestino - null
ViagemFinalizada - false
DistanciaTotal - null

4 - Iniciou Viagem:

Etapa - 4
StatusSolicitacao - "Em viagem."
NomePrestador - "João"
Veiculo - "Celta"
Cor - "Vermelho"
Placa - "DNU5060"
PrevisaoChegadaOrigem - null
DataHoraChegouOrigem - null
PrevisaoChegadaDestino - 15/09/2021 12:05:00
ViagemFinalizada - false
DistanciaTotal - null

5 - Finalizou:

Etapa - 5
StatusSolicitacao - "Viagem finalizada"
NomePrestador - "João"
Veiculo - "Celta"
Cor - "Vermelho"
Placa - "DNU5060"
PrevisaoChegadaOrigem - null
DataHoraChegouOrigem - null
PrevisaoChegadaDestino - null
ViagemFinalizada - true
DistanciaTotal: 5.53

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "errors": {
        "solicitacaoID": [
            "The value 'x' is not valid."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-6aa60e18f3760fa8aeb3d3e77bd52b4f-e5aae9442b7d5472-00"
}

Consultar Valor Final Solicitacão

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/ValorSolicitacao?solicitacaoID={solicitacaoID} Método: GET

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
solicitacaoID Integer Sim

Ex. de consumo:

Header:

GET /api/External/ValorSolicitacao?solicitacaoID=4103 HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Valor",
        "resultado": {
            "Valor": 8.03,
            "TipoPagamento" : "Dinheiro"
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 161,
            "mensagemErro": "SolicitacaoID informado não pertence à empresa."
        }
    }
}

Consultar Configurações

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/Configuracoes Método: GET

Ex. de consumo:

Header:

GET /api/External/Configuracoes HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 200 OK

{
    "Resultado": {
        "ok": true,
        "descricao": "Configuracoes",
        "resultado": {
            "PermiteInformarDestinoDepois": true
        }
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 200,
            "mensagemErro": "Ocorreu um erro no processamento da requisição. ID do log: 12834"
        }
    }
}

Avaliar Motorista

URL: https://webapiexterna-{NOMEAPP}.azurewebsites.net/api/External/Avaliacao?solicitacaoID={solicitacaoID}&nota={nota}&comentario={comentario} Método: POST

Parâmetros

Propriedade Tipo Tamanho Obrigatório Descrição
solicitacaoID Integer Sim
nota Integer Sim
comentario String Não Caso a nota seja menor que 5 este campo se torna obrigatório.

Ex. de consumo:

Header:

POST /api/External/Avaliacao?solicitacaoID=4102&nota=4&comentario=teste HTTP/1.1
Host: webapiexterna-cluber2.azurewebsites.net
Authorization: Basic NCQhVnpMJnA0Wmo1OjVualBlJretc1QyYQ==

Ex. de retorno bem sucedido:

Status: 201 Created

{
    "Resultado": {
        "ok": true,
        "descricao": "Avaliação Gravado com sucesso!",
        "resultado": null
    }
}

Ex. de retorno com erro:

Status: 400 Bad Request

{
    "Resultado": {
        "ok": false,
        "descricao": "Verifique a mensagem de erro.",
        "resultado": {
            "codigo": 170,
            "mensagemErro": "Avaliação não pertence ao cliente e prestador da SolicitacaoID informada."
        }
    }
}

Referência

StatusSolicitacaoID (Viagem)

Código Descrição
1 Pedido criado
2 Aguardando Motorista
3 Em Viagem
4 Viagem Finalizada
5 Cancelado pelo Motorista
6 Cancelado pelo Cliente
7 Excedeu Tentativas
8 Excedeu Raio de atendimento
9 Cancelado pelo Administrador
10 Cancelado pelo Sistema

StatusSolicitacaoID (Entregas)

Código Descrição
1 Pedido Criado
2 Aguardando Coleta
3 Em Andamento
4 Solicitação Finalizada
5 Cancelado pelo Motorista
6 Cancelado pelo Cliente
7 Buscando Motorista
8 Procurando Motorista
9 Cancelado pelo Administrador
10 Cancelado pelo Sistema
11 Aguardando Confirmação
12 Aguardando Pagamento
13 Coleta Não Realizada
14 Entrega Não Realizada
15 Excluída

Códigos de Erros da API

Códigos retornados em caso de erro, identificando o motivo do erro e suas respectivas mensagens.

Código Descrição do erro
100 ServicoItemID não pode ser nulo.
101 ServicoItemID informado não foi encontrado no cadastro.
102 enderecoOrigem não pode ser nulo.
103 Não foi possivel recuperar as informações detalhadas com base no endereço de origem informado.
104 Não foi possivel definir a latitude/longitude com base no endereço de origem informado.
105 lstDestino não pode ser nulo.
106 lstDestino deve possuir ao menos um endereço.
107 Não foi possivel recuperar as informações detalhadas com base no endereço de destino informado.
108 Não foi possivel definir a latitude/longitude com base no endereço de destino informado.
110 TipoPagamentoID informado não foi encontrado no cadastro.
111 TipoPagamentoID informado não pode ser 0 (zero) ou nulo.
112 TipoPagamentoID informado não aceito pelo serviço.
113 TipoPagamentoID informado não aceito por solicitação do tipo viagem.
114 TipoPagamentoID informado não aceito em solicitações feitas via integração.
115 TipoPagamentoID informado não aceito por solicitação do tipo entrega.
120 ClienteID não pode ser nulo.
121 ID informado não foi encontrado no cadastro.
122 ID informado não está vinculado à empresa.
123 ClienteID informado é diferente do cadastro de integração.
124 ServicoItemID informado é do tipo conveniado, e não está vinculado ao cliente / empresa.
125 ServicoItemID informado deve ser do tipo viagem.
126 ServicoItemID informado deve ser do tipo entrega.
127 Não foi encontrado cadastro com os dados informados.
130 lstMercadoria - ServicoItemID exige pelo menos uma mercadoria informada em cada endereço de destino.
131 lstMercadoria - ServicoItemID exige que sejam informadas as medidas (Altura, Largura e Comprimento) das mercadorias.
132 lstMercadoria - ServicoItemID exige que a Quantidade seja informada (não pode ser 0 (zero) ou nulo).
133 lstMercadoria - ServicoItemID exige que o Valor seja informado (não pode ser 0 (zero) ou nulo).
134 lstMercadoria - ServicoItemID exige que CategoriaMercadoriaID seja informado (não pode ser 0 (zero) ou nulo).
135 lstMercadoria - CategoriaMercadoriaID informado não foi encontrado no cadastro.
136 lstMercadoria - Descricao deve ser informado e possuir 3 (três) ou mais caracteres.
137 lstMercadoria - ServicoItemID exige que o Peso seja informado (não pode ser 0 (zero) ou nulo).
140 Servico não disponível. Verifique se os parâmetros e as configurações atendem aos requisitos da solicitação.
150 Este usuário não possui uma empresa definida.
160 SolicitacaoID informado não foi encontrado na base de dados.
161 SolicitacaoID informado não pertence à empresa.
162 Não encontrado nenhum dado com esta SolicitacaoID.
163 SolicitacaoID informado não pode ser 0 (zero) ou nulo.
170 Avaliação não pertence ao cliente e prestador da SolicitacaoID informada.
199 Model ausente ou inválido. Verifique o layout do json de request, e se o Content-Length informado no header está correto.
200 Ocorreu um erro no processamento da requisição. ID do log:

Copyright © 2020 DevBase Tecnologia. Todos os direitos reservados.

⚠️ **GitHub.com Fallback** ⚠️