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:
Agentes das Solicitações e Estimativas
Os principais agentes das solicitações são os condutores (entregadores).
Para otimizar seu negócio, é possível criar categorias e associar os condutores a elas, como uma categoria específica para carregar produtos delicados.Antes da solicitação, a empresa 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 de entrega 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 headerapi-key:
Authorization do tipo Basic:
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.
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 retorna429.
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 (entregas/* 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/entregas/estimativas, /api/v2/integracao/entregas/programadas/estimativas e /api/v2/integracao/entregas/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 por um fator, calculado levando em conta o tamanho da operação da central. Por isso, na coluna Limite, os valores aparecem como limite base * fator. Quando a central não possui um fator específico configurado, o fator padrão é 1.
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 receber429.
Quando o grupo tem mais de um limite de bloqueio, os headers refletem o mais restritivo (o de menor saldo). Grupos sem bloqueio configurado (apenas log) não retornam esses headers.
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âmetroslimite e página:
limite: número de registros por página (default 20, máximo 100)página: página atual (default 1)