Skip to main content

​
Tipos de Solicitações e Pagamento

As solicitações podem ser feitas de imediato ou programadas para o futuro, cada uma identificada por números diferentes. Após o disparo de uma solicitação programada, uma nova solicitação é criada no sistema.

Formas de Pagamento Suportadas

Todas as solicitações estão associadas a uma forma de pagamento. As opções incluem:
As solicitações podem ter vários objetivos, dependendo do modelo de negócio e do tipo de cliente:

Passageiro

Levar uma pessoa para o destino solicitado.

Empresa

Transportar o funcionário de uma organização.

Estabelecimento

Levar o hóspede de um hotel para o destino.

​
Agentes das Solicitações e Estimativas

Os principais agentes das solicitações são os condutores (motoristas, mototaxistas e taxistas). Para otimizar seu negócio, é possível criar categorias e associar os condutores a elas, como uma categoria específica para carregar compras.Antes da solicitação, o cliente pode obter uma estimativa de custo, que é sempre feita por categoria. Cada categoria tem suas tarifas definidas pela central.

​
Ciclo de Vida das Solicitações

As solicitações passam por várias etapas e subetapas. Os registros de solicitação não alteram o status da solicitação. Segue a estrutura correta do ciclo:

​
Solicitações Programadas

Solicitações aceitas e canceladas por um condutor antes do início podem ser redistribuídas, ocasionando a repetição de alguns status. Solicitações programadas seguem um ciclo específico de estados:

​
Autorização

Toda requisição deve incluir sua chave de API no header api-key:
Também é necessário informar as credenciais de Authorization do tipo Basic:
Depois isso vira algo como:
No final, o formato da request com os campos de autorização ficam similar a:
Requisições sem chave ou com chave inválida retornam 400 ou 403.

​
Usuário autenticado

O usuário autenticado é a entidade utilizada para realizar as requisições na API da Machine. Assim como qualquer outro, este possui um cargo e suas permissões. O usuário autenticado terá acesso às endpoints conforme às permissões concedidas na seção Integração em: Minha equipe > Usuário > Permissões. Há dois logins que permitem acesso às endpoints: login de empresa (quando o usuário é de uma empresa) e o login da central (quando o usuário é da central). O login também irá limitar alguns acessos, pois usuários de empresa terão acesso apenas às informações associadas a sua empresa.

​
Padrão da API

Todas as respostas da nossa API são em JSON. Usamos como retorno os códigos HTTP padrão para indicar tanto o sucesso de uma requisição, quanto para indicar falhas. Os principais retornos são:
  • 200: Sucesso.
  • 400: Os dados serão validados e, se faltar algum parâmetro obrigatório, será gerado um código de retorno HTTP 400. Outros erros de validação, como erros associados a regra de negócio, serão tratados com códigos de erro específicos e mensagens explicativas.
  • 404: Endpoint não encontrado, revise a URL passada.
  • 500: Erro interno, contate o nosso suporte.
Caso ocorra algum erro na autenticação básica, um erro padrão de código 1 informando “usuário e/ou senhas inválidas”, será retornado. Caso a chave API não seja informada, um erro padrão será retornado:

​
Ambientes de integração com a API

Para garantir uma integração eficiente e segura, a API oferece integração com dois ambientes distintos: Homologação (ou Testes) e Produção.

​
Ambiente de Homologação (Testes)

  • Finalidade: Este ambiente é destinado exclusivamente a testes de integração, desenvolvimento e validação de funcionalidades. Ele permite que você experimente e refine a comunicação com a API sem qualquer risco de afetar as operações reais da central.
  • URL de Acesso: https://api-vendas.taximachine.com.br/api/v2/integracao
  • Observação: Todas as ações realizadas neste ambiente são simuladas e não impactarão os dados ou operações da central em produção.

​
Ambiente de Produção

  • Finalidade: Este é o ambiente principal para atuação real com a central. Após a conclusão bem-sucedida dos seus testes no ambiente de Homologação, você deve migrar para este ambiente para iniciar as operações reais.
  • URL de Acesso: https://api.taximachine.com.br/api/v2/integracao
  • Observação: Utilize este ambiente somente quando estiver pronto para interagir de fato com a central, pois as ações aqui são reais e permanentes.

​
Rate limit

O gateway aplica rate limit por janela deslizante de 60 segundos. Quando a requisição excede o limite de bloqueio, a API retorna 429. Os limites são aplicados por api-key. A avaliação segue a prioridade das regras: grupos específicos são avaliados antes dos prefixos mais genéricos (corridas/* e, por fim, /api/v2/integracao/*). O limite é contado por grupo de endpoints, e não por endpoint isolado: todas as chamadas às rotas de um mesmo grupo somam no mesmo contador. Por exemplo, chamar /api/v2/integracao/corridas/estimativas, /api/v2/integracao/corridas/programadas/estimativas e /api/v2/integracao/corridas/empresas com a mesma chave em menos de um minuto consome 3 requisições do grupo “Estimativas e empresas”, e não 1 de cada endpoint. Os valores da tabela são limites base. O limite efetivo de cada grupo é o limite base multiplicado pela faixa da central. A faixa é um multiplicador inteiro, a partir de 1, definido para cada central. Por isso, na coluna Limite, os valores aparecem como limite base * faixa. Quando a central não possui faixa definida, vale a faixa 1. O limite de mensagens da corrida vale para o envio; a leitura (/api/v2/integracao/mensagens/corridas/passageiro/* e /api/v2/integracao/mensagens/corridas/condutor/*) segue o limite Padrão.

​
Limites por recurso

Alguns endpoints têm, além do limite do grupo, um limite por recurso informado na requisição: a mesma api-key só pode operar o mesmo recurso, identificado na requisição, um número fixo de vezes por minuto. Esses limites são fixos e não são multiplicados pela faixa. Nas notificações, o envio individual conta por passageiro_id, e no envio em lote o conjunto de passageiros informado em passageiros é tratado como um único recurso: o mesmo conjunto só pode receber 4 envios por minuto. Lotes com mais de 100 passageiros contam apenas no limite do grupo. Requisições sem identificador (por exemplo, listagens por filtro) contam apenas no limite do grupo. Os limites valem ao mesmo tempo: exceder qualquer um deles retorna 429. O contador por recurso é separado para cada api-key, então o consumo de um integrador não afeta o de outro.

​
Headers de rate limit

Nas respostas dos endpoints com limite de bloqueio configurado, o gateway informa o consumo da janela atual. Use esses headers para se auto-regular antes de receber 429. Quando mais de um limite de bloqueio se aplica à requisição (por exemplo, o do grupo e um limite por recurso), os headers refletem o mais restritivo (o de menor saldo). Não existe header de reset: como a contagem usa janela deslizante, não há um instante único de zeragem do contador. Na resposta 429, o tempo de espera continua sendo indicado pelo header Retry-After, em segundos.

​
Paginação

Alguns endpoints de listagem retornam todos os registros disponíveis. Porém, alguns possuem paginação, controlável pelos parâmetros limite e página:
  • limite: número de registros por página (default 20, máximo 100)
  • página: página atual (default 1)
Exemplo: