Desenvolvedores / API

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
  • 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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».
Ver todos os endpoints →

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}
Ver na referência →

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
Ver na referência →

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
Ver na referência →

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
Ver na referência →

Agendamentos

Horários livres com as regras da agenda (expediente, boxes e feriados), propostas e reservas confirmadas.

    Ver na referência →

    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
    Ver na referência →

    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}
    Ver na referência →

    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
    Ver na referência →

    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
    Ver na referência →

    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
    Ver na referência →

    Webhooks

    Assinaturas por evento, com assinatura HMAC-SHA256, novas tentativas e um envio de teste quando quiser.

    Alguns eventos

    lead.acceptedvehicle.readyinvoice.issuedpayment.receivedappointment.proposed+37 a mais
    Ver na referência →

    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
    Ver na referência →

    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.

    Incluído
    Vem com qualquer plano do Promec.
    0€/mês
    sem impostos
    Ver planos do Promec
    • 1 chave live
    • Só leitura, todas as áreas
    • 2.000 requisições por dia
    • Ao atingir a cota, pausa até 00:00 UTC
    Integrações próprias
    Developer
    Para conectar as suas ferramentas, aceitar orçamentos e faturar.
    19€/mês
    sem impostos
    Falar com vendas
    • 5 chaves live
    • Leitura e escrita
    • Webhooks
    • Aceitar orçamentos e faturar
    • 20.000 requisições por dia
    Business
    Quando a integração envia mensagens ou atende os canais com o seu assistente.
    49€/mês
    sem impostos
    Falar com vendas
    • 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
    Partner
    Para software que atende muitas oficinas.
    a partir de5€/oficina/mês
    sem impostos
    Consultar o Partner
    • 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.

    3 meses por 1 €