Conecte sua oficina aos outros sistemas que você usa
Com a API REST do Promec, seu contador, seu ERP, o gestor de frota de um cliente ou o seu próprio site leem e gravam dados da oficina sem planilhas indo e voltando por e-mail. Quem ativa é a gerência da oficina, com permissões por área e um registro de cada requisição.
- 38endpoints na v1
- 27eventos de webhook
- 60requisições por minuto por chave
curl https://sua-oficina.example/api/v1/ping \ -H "Authorization: Bearer pt_test_9f2c…"
{
"ok": true,
"key": { "name": "CRM", "environment": "test",
"scopes": ["clients:read", "budgets:read"] },
"rate_limit": {
"per_minute": { "limit": 60, "remaining": 59 },
"per_day": { "limit": 2000, "remaining": 1999 }
},
"version": "v1"
}- Finalidade declarada em cada chave
- Cada chave presa a uma só oficina
- Webhooks assinados HMAC-SHA256
- Registro de requisições por 90 dias
- Idempotency-Key nas gravações
- Faturas emitidas só no sistema
Para que as oficinas usam
Integrações que realmente nos pedem. Se a sua não está aqui, conte para a gente: quase sempre dá para resolver com os endpoints que já existem.
Contador e contabilidade
O escritório de contabilidade baixa todo mês as faturas emitidas, com PDF e recebimentos, sem precisar pedir por e-mail. Pela API as faturas só são consultadas; a emissão continua no sistema para a numeração fiscal ficar correta.
ERP do grupo ou da concessionária
Se a oficina faz parte de um grupo, sincronize clientes, veículos e orçamentos com o sistema central e receba um aviso assim que uma fatura for emitida.
Frotas e locadoras
O gestor da frota acompanha em que etapa está cada veículo e quando vence a vistoria, e recebe um webhook quando ele entra na oficina, quando fica pronto e quando é entregue.
Fornecedores de peças
Um distribuidor pode abrir orçamentos já com o código da peça em cada item, ou ler os itens de um serviço para separar o pedido.
Seu site ou app
Seu site consulta os horários livres da agenda real e propõe o agendamento. Você confirma com um clique ou, no modo de reserva direta, ele já entra confirmado.
Make, n8n ou Zapier
Receba os eventos por webhook e monte o fluxo que precisar: uma tarefa no CRM quando um orçamento é recusado ou uma linha na planilha a cada pagamento recebido.
Como funciona
Da primeira chave à integração em produção, sem configurar servidor. A API já vem no seu Promec.
- Crie uma chave de testeEm «Desenvolvedores / API», a gerência da oficina cria a chave com um nome, a finalidade da integração e as permissões por área. A chave completa aparece uma única vez.
- Chame o /pingCom a URL da sua oficina (https://<seu-dominio>/api/v1). Ele devolve as permissões da chave e quanto ainda resta da cota de hoje.
- Desenvolva com dados reaisAs chaves pt_test_ leem os dados da oficina, mas não criam, alteram nem enviam nada, e não gastam cota. Errar não custa nada.
- Vá para live e assine webhooksQuando tudo bater, crie uma chave pt_live_ e cadastre a URL que vai receber os eventos. Cada alteração fica registrada como «API · nome da chave».
curl -X POST https://sua-oficina.example/api/v1/budgets \ -H "Authorization: Bearer pt_live_4b7e…" \ -H "Idempotency-Key: 7c1d0e52-9a3f-4f0b" \ -H "Content-Type: application/json" \ -d '{"client_id": 1204, "vehicle_id": 871, "lines": [{"description": "Troca de óleo e filtro", "quantity": 1, "unit_price": 65, "line_type": "labor"}]}'
{
"id": 5821,
"status": "Pendiente",
"channel": "API",
"client_id": 1204,
"totals": { "base": 65, "tax": 13.65, "total": 78.65 },
"tracking_url": "…/public/seguimiento?id=…"
}Recursos disponíveis
O que uma integração pode ler e gravar na versão 1. Cada recurso tem a sua permissão, então cada chave só vê o que precisa.
Clientes
Busca por nome, telefone ou e-mail, cadastro e edição de clientes com os dados de contato.
- GET
/clients - POST
/clients - GET
/clients/{id} - PATCH
/clients/{id}
Veículos
Busca por placa ou por cliente, cadastro e edição, com quilometragem e vencimento da vistoria.
- GET
/vehicles - POST
/vehicles - GET
/vehicles/{id} - PATCH
/vehicles/{id}
Orçamentos
Criar orçamentos com os itens, mudar o status e anexar fotos ou PDF. Aprovar, só o cliente pelo link dele.
- GET
/budgets - POST
/budgets - GET
/budgets/{id} - POST
/budgets/{id}/lines - +4 a mais
Faturas e PDF
Faturas emitidas com itens, totais por alíquota, recebimentos e o PDF original. Só leitura.
- GET
/invoices - GET
/invoices/{id} - GET
/invoices/{id}/pdf
Agendamentos
Horários livres com as regras da agenda (expediente, boxes e feriados), propostas e reservas confirmadas.
Catálogo
Serviços e tarifas da oficina, para o seu site ou configurador mostrar os mesmos preços.
- GET
/catalog/services - GET
/catalog/rates
Comunicações
Registro de e-mails, SMS, WhatsApp e ligações. No plano Business, envio de e-mail e SMS.
- GET
/communications - GET
/logs - POST
/email - POST
/sms
Webhooks
Assinaturas por evento, com assinatura HMAC-SHA256, novas tentativas e um envio de teste quando quiser.
Alguns eventos
Feita para integrações que não quebram
Os detalhes que costumam dar dor de cabeça numa integração, resolvidos de fábrica.
Chaves criadas pela gerência
O dono ou gerente da oficina cria cada chave com um nome, a finalidade de uso e as permissões. A chave completa aparece uma única vez; depois só o prefixo fica visível.
Permissões por área
Clientes, veículos, orçamentos, faturas, agendamentos, catálogo e comunicações, com leitura e, onde faz sentido, escrita. A chave do contador não precisa ver a agenda.
Teste e produção
As chaves pt_test_ leem dados reais, mas não criam nem alteram nada, e não consomem cota. Quando a integração estiver funcionando, você cria uma pt_live_.
Webhooks assinados
O Promec chama a sua URL quando algo acontece: 27 eventos, de «orçamento aprovado» a «veículo pronto». Cada entrega é assinada com HMAC-SHA256 e reenviada até 5 vezes se o seu servidor não responder.
Limites à vista
60 requisições por minuto por chave (dá para ampliar até 600) mais a cota diária do plano. Toda resposta traz X-RateLimit-Remaining e, se passar do limite, um 429 com Retry-After.
Gravações sem duplicidade
Todo POST leva Idempotency-Key: se o seu sistema repetir a mesma operação por uma queda de rede, não aparece um segundo cliente nem um segundo orçamento.
Segurança e proteção de dados
Uma integração não deveria abrir mais portas do que precisa. Foi pensada assim:
Cada chave é de uma só oficina
Só o hash da chave é guardado, ligado à instância da oficina: ela não funciona em nenhuma outra e ninguém consegue recuperá-la, nem a gente.
Finalidade obrigatória
Ao criar a chave é preciso informar para que os dados serão usados, como pede a legislação de proteção de dados. Isso fica junto da chave e no registro.
O que é interno não sai
Custos, margens, observações internas e orçamentos de uso interno não aparecem em nenhuma resposta. Da equipe da oficina só aparecem o id e o nome.
Registro de cada requisição
Qual chave, de qual IP, para qual endpoint e com qual resultado. Fica guardado por 90 dias e pode ser consultado na mesma seção.
IPs permitidos e validade
Você pode limitar uma chave aos IPs do fornecedor que a usa e definir uma data de validade. Revogar vale na hora.
Quem assina é o cliente
A aprovação de um orçamento é sempre do cliente, pelo link assinado dele; a API não pode aprovar em nome dele.
Planos da API
São separados do plano do Promec. Você começa no Incluído e só muda se precisar gravar dados, receber webhooks ou ter mais volume.
- 1 chave live
- Só leitura, todas as áreas
- 2.000 requisições por dia
- Ao atingir a cota, pausa até 00:00 UTC
- 5 chaves live
- Leitura e escrita
- Webhooks
- 20.000 requisições por dia
- Chaves ilimitadas
- Tudo do Developer
- Envio de e-mail e SMS pela API (mensagens cobradas à parte)
- 100.000 requisições por dia
- Suporte por e-mail
- Para empresas que conectam o próprio produto a várias oficinas
- Cota, chaves e permissões sob medida
- Preço por volume
Preços sem impostos, em euros como os demais planos do Promec. Chaves de teste não têm custo nem contam na cota, assim como os testes feitos pelo painel. Se em um mês o Developer ou o Business passarem da cota (cota diária × dias do mês), o excedente é cobrado a 1 € a cada 1.000 requisições.
Perguntas frequentes
Preciso pagar para usar a API?
Não. O plano Incluído vem com qualquer plano do Promec: uma chave só de leitura e 2.000 requisições por dia. Você só paga se precisar gravar dados, usar webhooks ou ter mais volume.
Onde encontro a URL da API da minha oficina?
Na seção «Desenvolvedores / API» do Promec. Cada oficina funciona no próprio domínio, então a URL base tem o formato https://<seu-dominio>/api/v1.
Dá para emitir faturas pela API?
Não. As faturas podem ser consultadas com PDF e recebimentos, mas a emissão é feita no sistema para manter a numeração e a comunicação com o fisco corretas.
E se a integração errar?
Uma chave de teste não consegue alterar nada. Com uma live, cada mudança fica no histórico do cliente ou do orçamento como «API · nome da chave», e a chave pode ser revogada na hora.
Existe SDK ou coleção do Postman?
Com o arquivo OpenAPI 3.1 você gera um cliente na linguagem que preferir. Dentro do Promec também tem a coleção do Postman e um painel para testar cada endpoint com a sua chave.
Desenvolvo software para oficinas. Posso me conectar a várias?
Sim, com o plano Partner: cada oficina cria uma chave para o seu produto e combinamos o preço por oficina conforme o volume. Fale com a gente.
O que acontece se eu passar do limite de requisições?
Cada chave aceita 60 requisições por minuto. Se passar disso, a API responde 429 com o cabeçalho Retry-After e o seu sistema só precisa esperar esses segundos. No plano Incluído, ao esgotar a cota diária a chave pausa até 00:00 UTC; no Developer e no Business as requisições continuam e o excedente é cobrado a 1 € a cada 1.000.
A API pode aprovar um orçamento no lugar do cliente?
Não. A aprovação é sempre assinada pelo cliente no link de acompanhamento. Se uma integração tentar marcar um orçamento como aprovado, recebe um 403 com o link que deve ser enviado ao cliente.
Tem uma integração em mente?
Conte o que você quer conectar e indicamos os endpoints certos e o plano que faz sentido.