{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1f445058-aa61-47c1-a6b7-53a0ba20ace5","name":"Documentação Machine - Entregas","description":"<img src=\"https://content.pstmn.io/ac0c27a3-91a6-493e-90cc-de99bfd14ac3/bG9nb21hY2hpbmVidy5wbmc=\">\n\nBem-vindo à API da Machine! Este documento guiará você na integração do seu sistema com o nosso de maneira simples e eficaz.\n\nPara garantir uma integração tranquila e bem-sucedida, é essencial ter todas as informações necessárias à mão. A Machine está em constante evolução, por isso, recomendamos acompanhar nossos informes e o changelog para se manter atualizado sobre as novidades na integração.\n\n## Quem Somos?\n\nA Machine é um produto [Gaudium](https://www.gaudium.global/), projetado para fornecer tecnologia que permite a operação eficiente e segura das centrais (empresas de mobilidade urbana, como transporte de passageiros e entregas). Nossa plataforma oferece a tecnologia necessária para que os condutores possam realizar seus serviços, movimentando-se do ponto A ao ponto B conforme as solicitações recebidas.\n\n## Tipos de Solicitações e Formas de Pagamento\n\nAs 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. Todas as solicitações estão associadas a uma forma de pagamento. As opções de pagamento incluem:\n\n- Dinheiro (`D`).\n    \n- Débito (`B`).\n    \n- Crédito (`C`).\n    \n- Pix (`X`).\n    \n- PicPay (`P`).\n    \n- WhatsApp (`H`).\n    \n- Faturado (`F`).\n    \n- Carteira de Créditos (`R`).\n    \n\nAs solicitações de entregas podem ter vários objetivos, dependendo do modelo de negócio e do tipo de cliente:\n\n- **Entrega de refeições**: Levar a refeição de um restaurante até o cliente final.\n    \n- **Entrega de encomendas**: Levar encomendas de lojas ou centrais de distribuição até o cliente final.\n    \n\n## Agentes das Solicitações e Estimativas\n\nOs 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.\n\n## Ciclo de Vida das Solicitações\n\nAs solicitações de entregas passam por várias etapas e subetapas, detalhadas a seguir. Nota-se que os registros de solicitação não alteram o status da solicitação\n\n- **Distribuindo (**`D`**)**: Solicitação aberta e ainda não atribuída a um condutor.\n    \n- **Aguardando aceite (**`G`**)**: Esperando um condutor aceitar a solicitação.\n    \n- **Pendente ou Buscando Condutor (**`P`**)**: Solicitação não aceita, aguardando aceitação.\n    \n- **Não atendida (**`N`**)**: Nenhum condutor aceitou a solicitação.\n    \n- **Aceita (**`A`**)**: Solicitação aceita por um condutor.\n    \n    - **A Caminho**: Condutor está a caminho do local de coleta do pedido.\n        \n    - **Aguardando no Estabelecimento**: Condutor chegou ao local de coleta.\n        \n- **Em andamento (**`E`**)**: Condutor coletou o pedido e iniciou a entrega.\n    \n- **Finalizada (**`F`**)**: Condutor entregou o pedido no local de destino.\n    \n- **Em Espera (**`S`**)**: Solicitação em espera até a conclusão de uma anterior.\n    \n- **Cancelada (**`C`**)**: Solicitação cancelada\n    \n- **Agrupada (**`U`**)**: Solicitação agrupada\n    \n\n## Solicitações Programadas\n\nSolicitaçõ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:\n\n- **Aguardando (**`A`**):** Aguardando horário de disparo.\n    \n- **Disparada (**`D`**):** Solicitação programada disparada.\n    \n- **Cancelada (**`C`**):** Solicitação cancelada.\n    \n- **Erro (**`X`**):** Problema no processo da solicitação.\n    \n- **Agrupada manualmente (****`G`****)**: Agrupada com uma solicitação programada\n    \n- **Agrupada automaticamente (**`H`**)**: Agrupada com uma solicitação programada de forma automática\n    \n- **Agrupada com uma solicitação (**`U`**)**: Agrupada com uma solicitação em andamento\n    \n\n## Primeiros Passos\n\nPassos iniciais para iniciar sua integração com a Machine:\n\n1. **Autorização**: Utilize uma API key e um login válido. Caso você seja um usuário de central, entre em contato com o nosso suporte. Caso contrário, entre em contato com a central responsável pela integração para mais informações.\n    \n2. **Importe essa documentação para o Postman**: Acesse o link da coleção no Postman fornecido e importe o arquivo JSON da coleção diretamente no Postman.\n    \n3. **Atualize as variáveis**: Configure as variáveis de ambiente no Postman (descritas na seção \"Variáveis da coleção\"), conforme necessário.\n    \n\nPronto! Agora você está preparado para explorar a nossa integração para que, juntos, possamos crescer ainda mais.\n\n## [Rate Limit](#ratelimit)\n\nPor padrão, a maioria dos endpoints tem um limite de 50 requisições por minuto. No entanto, alguns endpoints podem ter limites diferentes, conforme listado abaixo:\n\n| **Endpoint** | **Rate Limit** |\n| --- | --- |\n| /api/integracao/solicitacaoStatus  <br>/api/integracao/sacarCreditosCondutor  <br>/api/integracao/saldoCreditosCondutor  <br>/api/integracao/recarregarCreditosCondutor  <br>/api/integracao/enviarMensagem  <br>/api/integracao/atualizarEmpresa  <br>/api/integracao/sacarCreditosEmpresa  <br>/api/integracao/saldoCreditosEmpresa  <br>/api/integracao/recarregarCreditosEmpresa | 4 requests/minuto. |\n| /api/integracao/solicitacao  <br>/api/integracao/recibo  <br>/api/integracao/posicaoCondutor  <br>/api/integracao/abrirSolicitacao | 100 requests/minuto. |\n| /api/integracao/consultarProgramada  <br>/api/integracao/condutor | 200 requests/minuto. |\n\n## Autorização.\n\n- A Machine utiliza uma chave de API para autorização.\n    \n- Você deve incluir uma chave de API em cada requisição à API da Machine com o cabeçalho `api-key`.\n    \n- A chave de API foi pré-preenchida como uma variável da coleção.\n    \n- Para se autenticar ao nosso sistema você deve realizar uma autenticação básica, isto é, deve informar o login e a senha de um usuário ativo da sua central ou empresa.\n    \n\nA autorização e login foi configurado no nível da coleção, então todas as requisições nesta coleção herdarão automaticamente o cabeçalho necessário para a autenticação básica.\n\n⚠ **Lembre-se de que a sua api-key, quando usada em conjunto com a autenticação básica, concede acesso a todos os recursos e é o que define qual central está acionando a nossa API. Portanto, é crucial que os responsáveis mantenham-nas em locais seguros e não as exponham no lado do cliente da aplicação**. [<b>Saiba mais sobre o uso de variáveis no Postman</b>](https://learning.postman.com/docs/sending-requests/variables/#initial-and-current-values)\n\n## Usuário Autenticado\n\nO 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**.\n\nHá 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.\n\n## Padrão da API\n\nA nossa API segue o padrão REST e todas as suas respostas são em JSON.\n\nUsamos 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:\n\n- **200**: Sucesso.\n    \n- **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.\n    \n- **404**: Endpoint não encontrado, revise a URL passada.\n    \n- **500**: Erro interno, contate o nosso suporte.\n    \n\nCaso 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.\n\nCaso a chave API não seja informada, um erro padrão será retornado:\n\n``` json\n{\n    \"success\": false,\n    \"errors\": [\n      \"Chave da app não informada.\"\n    ]\n}\n\n ```\n\n## Ambientes de Integração com a API\n\nPara garantir uma integração eficiente e segura, a API oferece integração com dois ambientes distintos: Homologação (ou Testes) e Produção.\n\n### Ambiente de Homologação (Testes)\n\n- **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.\n    \n- **URL de Acesso**: [https://api-vendas.taximachine.com.br/api/integracao](https://api-vendas.taximachine.com.br/api/integracao)\n    \n- **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.\n    \n\n### Ambiente de Produção\n\n- **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.\n    \n- **URL de Acesso**: [https://api.taximachine.com.br/api/integracao](https://api.taximachine.com.br/api/integracao)\n    \n- **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.\n    \n\n## Variáveis da coleção\n\nA coleção utiliza das seguintes variáveis:\n\n| Variáveis | Descrição |\n| --- | --- |\n| `base_url` | Deve conter a URL em que será feita as requisições. |\n| `default_api_key` | Deve conter a sua chave API. |\n| `basic_auth_username` | Deve conter o login do usuário autenticado. |\n| `basic_auth_password` | Deve conter a senha do usuário autenticado. |\n\n## Changelog\n\nPara ficar por dentro de todas as atualizações e melhorias que implementamos, recomendamos que você verifique nosso [changelog](https://www.machine-updates.com/) regularmente. Nele, você encontrará um registro detalhado de todas as mudanças, correções de bugs e novos recursos adicionados ao nosso sistema.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"30402848","collectionId":"1f445058-aa61-47c1-a6b7-53a0ba20ace5","publishedId":"2s9YkgDkKa","public":true,"publicUrl":"https://documenter-api.postman.tech/view/30402848/2s9YkgDkKa","privateUrl":"https://go.postman.co/documentation/30402848-1f445058-aa61-47c1-a6b7-53a0ba20ace5","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5DB0D9"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"dark","themes":[{"name":"dark","logo":"https://content.pstmn.io/2c55335d-301b-4606-a4da-f21ef4a10e22/aW1hZ2UgKDIpLnBuZw==","colors":{"top-bar":"212121","right-sidebar":"555555","highlight":"5DB0D9"}},{"name":"light","logo":"https://content.pstmn.io/ea1157d8-3717-492e-a96a-ede1e9e49c4c/aW1hZ2UgKDIpLnBuZw==","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5DB0D9"}}]}},"version":"8.10.1","publishDate":"2024-06-28T15:50:39.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/ea1157d8-3717-492e-a96a-ede1e9e49c4c/aW1hZ2UgKDIpLnBuZw==","logoDark":"https://content.pstmn.io/2c55335d-301b-4606-a4da-f21ef4a10e22/aW1hZ2UgKDIpLnBuZw=="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/47248e88e46ab5f7e6fbc689382b720b43f3ac29a2596b71fedcd3e0409d8ffa","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2s9YkgDkKa"}