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.
- 56endpoints na v1
- 42eventos 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
- Faturamento com a numeração fiscal do 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. O seu sistema também pode faturar um orçamento aprovado e registrar o recebimento: a fatura sai com a numeração fiscal do sistema.
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. E se você tem o seu próprio bot ou IA, ele pode responder os WhatsApp, SMS, chats e e-mails da oficina.
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_ da sua oficina leem os dados dela, mas não criam, alteram nem enviam nada, e não gastam cota. Para testar também gravações, aceitações, faturas e mensagens, use o ambiente de testes público.
- 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} - +1 a mais
Orçamentos
Criar orçamentos com os itens, mudar o status e anexar fotos ou PDF. Aceitá-los ou rejeitá-los em nome do cliente, com a evidência de quem e por qual canal.
- GET
/budgets - POST
/budgets - GET
/budgets/{id} - GET
/budgets/{id}/activity - +7 a mais
Faturas e PDF
Faturas emitidas com itens, totais por alíquota, recebimentos e o PDF original. Faturar um orçamento aprovado e registrar recebimentos, com a numeração fiscal do sistema.
- POST
/budgets/{id}/invoice - GET
/invoices - GET
/invoices/{id} - GET
/invoices/{id}/pdf - +1 a mais
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
Peças
Estoque, referências e preço de venda do inventário. O custo e o fornecedor nunca saem pela API.
- GET
/stock - GET
/stock/{id}
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
Conversas
WhatsApp, SMS, chat do site e e-mail em uma lista, como a Caixa de entrada do sistema: leia o histórico e responda como a oficina.
- GET
/conversations - GET
/conversations/{key}/messages - POST
/conversations/{key}/messages - GET
/messages/templates
Assistente externo
Escolha em quais canais o seu bot ou IA responde no lugar do assistente do sistema, com reserva automática se não responder em 10 minutos.
- GET
/settings/assistant - PUT
/settings/assistant
Webhooks
Assinaturas por evento, com assinatura HMAC-SHA256, novas tentativas e um envio de teste quando quiser.
Alguns eventos
Ambiente de testes
Instância pública com dados fictícios para testar gravações, aceitações, faturas e mensagens sem risco, com chaves pt_test_ de 30 dias.
- POST
/sandbox/keys - POST
/sandbox/simulate/message
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_ da sua oficina leem dados reais, mas não criam nem alteram nada, e não consomem cota. Para testar gravações, aceitações, faturas e mensagens existe um ambiente de testes público com dados fictícios. Quando a integração estiver funcionando, você cria uma pt_live_.
Webhooks assinados
O Promec chama a sua URL quando algo acontece: mais de 40 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.
A aceitação deixa rastro
Aceitar ou rejeitar um orçamento pela API exige uma permissão à parte (budgets:accept) e a evidência de quem aceita e por qual canal. Fica no histórico como «Aceito por API em nome do cliente», com o nome da chave.
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
- Aceitar orçamentos e faturar
- 20.000 requisições por dia
- Chaves ilimitadas
- Tudo do Developer
- Mensagens pela API (e-mail, SMS, WhatsApp e chat) e assistente externo nos seus canais (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?
Sim, com uma permissão à parte (invoices:write), a partir do plano Developer. A API usa o faturamento do próprio sistema: série, numeração sequencial, registro fiscal e lançamento contábil. Fatura-se um orçamento aprovado, nunca se cria uma fatura avulsa, e as retificações são feitas no sistema.
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?
Sim, com a permissão budgets:accept (plano Developer ou superior) e somente se você informar a evidência: quem aceita e por qual canal (telefone, pessoalmente, e-mail, WhatsApp…). Passa pela mesma regra de aceitação do sistema e no histórico fica «Aceito por API em nome do cliente» com o nome da chave. O cliente continua podendo aprovar pelo link de acompanhamento; a API nunca fornece esse link.
Existe um ambiente de testes?
Sim, público e gratuito: https://demo.programa-taller.es/desarrolladores-sandbox. Ele entrega uma chave pt_test_ de 30 dias com escrita habilitada sobre dados fictícios, restaurados a cada 2 horas. Nada sai de verdade (os envios são registrados como simulados) e os webhooks são emitidos normalmente, então você testa o ciclo completo. Suas chaves e webhooks são mantidos entre as reinicializações.
Posso usar meu próprio bot para responder aos clientes da oficina?
Sim, a partir do plano Business. Você ativa o «assistente externo» nos canais que quiser (WhatsApp, SMS, chat do site ou e-mail): cada mensagem do cliente chega a você pelo webhook message.received e você responde pela API. Se não responder em 10 minutos, ou se sua chave ou seu webhook parar de funcionar, o assistente do sistema responde por você.
Tem uma integração em mente?
Conte o que você quer conectar e indicamos os endpoints certos e o plano que faz sentido.