API para programadores

API para programadores

Ligue o seu software através de ações explícitas para fontes, processamento, resultados e gestão. Este guia descreve a API disponível dentro dos limites documentados desta versão. Utilizador, permissões, armazenamento e créditos continuam associados à conta Rapportly.

Prepare a integração em três passos

1. 1
   Escolha utilizador, ambiente e permissões

   Abra Conta → Integrações. Use uma chave de teste para o simulador fictício e uma chave de produção distinta para ações reais com dados fictícios. O administrador atribui apenas as permissões necessárias e um orçamento adequado.

2. 2
   Pratique a receção e os erros

   Comece pelo simulador. Depois importe os contratos da API e analise os exemplos sintéticos. Guarde os segredos no servidor; as alterações estão desativadas por predefinição na coleção.

3. 3
   Acompanhe um pedido completo

   Guarde dados e identificador, confirme início e estado final, leia o resultado, descarregue um ficheiro disponível e verifique o consumo. Faça este ensaio apenas num ambiente autorizado.

Criar a sua chave API

Endereço de base

https://api.rapportly.io/api/rapportly/v1

A chave pertence a um utilizador

Uma chave delega as permissões de um utilizador. O administrador define ambiente, limite de permissões, orçamento mensal e validade. O membro ativa a chave preparada e vê o segredo uma vez. Cada pedido também verifica permissões atuais do utilizador, plano e objeto. A gestão de chaves usa uma sessão de utilizador; as ações de produção, uma chave API. Guarde os segredos no servidor e revogue chaves perdidas em Conta → Integrações. Os eventos Zapier têm um contrato próprio.

GET https://api.rapportly.io/api/rapportly/v1/ping
Authorization: Bearer rply_<jouw_sleutel>

Use contratos e exemplos concretos

A OpenAPI de produção descreve contratos do código e assinala entradas ou respostas parciais. O inventário mostra esquemas pendentes. A coleção Postman começa com endereço inválido, chaves vazias e alterações desativadas. Importe para análise e envie conscientemente dados fictícios num ambiente autorizado. A importação ainda não foi testada.

• Descarregar a especificação OpenAPI de produção
• Descarregar a coleção Postman sintética
• Descarregar o percurso desde a fonte até ao ficheiro
• Descarregar o inventário de esquemas pendentes

Pratique primeiro com pedidos fictícios

Crie uma chave de teste e pratique pedidos em curso, resultados, erros e orçamento insuficiente. O simulador usa exemplos fixos e não custa créditos.

1. Em Conta → Integrações, crie ou ative uma chave Test com as permissões que pretende experimentar.
2. Consulte GET /test/scenarios e escolha uma ação devolvida. A lista respeita as permissões atuais.
3. Envie POST /test/opdrachten apenas com actie e scenario: succes, verwerking_mislukt, creditbudget_bereikt ou toegang_geweigerd. Cada novo exercício usa o seu próprio Idempotency-Key.
4. Guarde opdracht_id. Em bezig, consulte GET /test/opdrachten/{id} após cerca de cinco segundos. Verifique sempre o estado: HTTP200 também pode conter uma falha de processamento.

POST https://api.rapportly.io/api/rapportly/v1/test/opdrachten
Authorization: Bearer rply_test_<jouw_testsleutel>
Idempotency-Key: test-rapport-0001
Content-Type: application/json

{
  "actie": "rapport.start",
  "scenario": "succes"
}

O exemplo exige rapport.start na sua lista. Após um problema de ligação, repita os mesmos dados e Idempotency-Key.

• Descarregar o guia do simulador
• Descarregar a coleção Postman de exercícios
• Descarregar a OpenAPI do simulador

Obtenha apenas o necessário

Pesquise pastas de clientes, conversas e relatórios acessíveis. /acties mostra ações e permissões, /gebruik orçamento e reservas, /verzoeken histórico técnico. Um processamento em curso ainda não tem resultado. As ligações dos relatórios duram 15 minutos; leia novamente para obter outra.

Atualizar a gestão de clientes

O teu software pode alterar os modelos do escritório, guardar pesquisas pessoais, registar uma visita e criar um processo de acompanhamento. Usa as permissões de administração adequadas e confirma cada alteração. Lê primeiro a versão atual e mantém o mesmo identificador de pedido se a resposta se perder. A repetição de um pedido antigo não pode reverter uma alteração mais recente. O teste em produção verifica pesquisas, visitas e processos de acompanhamento, incluindo limpeza e revogação de chaves. Os modelos do escritório foram apenas lidos; a escrita foi testada localmente e em CI. O guia para transferência descreve as quatro rotas e os limites das provas correspondentes.

Comparar duas versões guardadas

Compara dois números de versão existentes do mesmo campo de texto de relatório guardado ou do mesmo campo de conversa guardado, sem novo processamento por IA. Este contrato foi testado localmente e em CI; o teste CRM em produção não comprova o comportamento da comparação em produção. O histórico em falta não é substituído pelo texto atual. As diferenças longas são truncadas para um máximo de 8000 carateres por lado, com indicação visível. A comparação não abrange PowerPoint, cálculos de orçamentos, cartas de acompanhamento ou formatação. As permissões de leitura e as condições de privacidade atuais continuam a aplicar-se.

Pedir uma estimativa prévia

POST /generatieplan apresenta passos e créditos previstos para relatório, proposta ou conversa. Use gebruik:lezen. Cálculo e definições de equipa são os mesmos do site.

Uma estimativa não inicia processamento nem debita créditos. Não é um preço máximo garantido. Mostre incertezas, como custos de leitura ainda desconhecidos. O início volta a verificar permissões e créditos.

Descarregar o guia de estimativas e exemplos

Inicie processamento a partir do seu software

A API liga processos, documentos, carregamentos, áudio, transcrição, pastas de clientes, estilos, saídas, workflows, Excel e mensagens dirigidas. Cada rota mantém dados, permissões, confirmações e controlo de versão próprios. Continuam válidos o processamento e a contabilização de créditos existentes. A resposta inicial confirma receção; consulte depois o estado. O inventário indica os contratos pendentes.

Crie primeiro um processo

Gere e guarde um UUID. Envie PUT /dossiers/{id} apenas com naam, até 200 caracteres. 201 significa criação; 200, repetição idêntica. O processo pertence ao utilizador e organização da chave, sem custo de créditos. Dados diferentes devolvem 409; processo inacessível ou eliminado, 404. GET /dossiers/{id} lê naam e klant_id com permissão de leitura.

PUT https://api.rapportly.io/api/rapportly/v1/dossiers/00000000-0000-4000-8000-000000000002
Authorization: Bearer rply_<jouw_sleutel>
Content-Type: application/json

{ "naam": "Voorbeeldproject" }

Relatório, proposta ou apresentação

Comece com dossierId e notities. tier é opcional: basis, standaard ou max. Sem perfil de estilo, a apresentação é neutra. Pode indicar stijlprofielId, klantId, bronOpnameIds e taal acessíveis. O estilo tem de corresponder ao tipo de documento. Propostas usam configurações empresariais e numeração segura; a API não as envia ao cliente.

POST https://api.rapportly.io/api/rapportly/v1/rapporten
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-rapport-2026-0001
Content-Type: application/json

{
  "dossierId": "00000000-0000-4000-8000-000000000002",
  "notities": "Team Atlas besprak de training. Noor plant de volgende bijeenkomst op donderdag.",
  "tier": "standaard"
}

Guarde versie_id e acompanhe GET /rapporten/{versie_id}, também para propostas e apresentações. Em klaar, resultaat contém ficheiros disponíveis: export_url para PDF, export_url_docx para Word e export_url_pptx para PowerPoint. As ligações duram 15 minutos. Em mislukt, verifique processamento e consumo antes de iniciar automaticamente outro pedido com nova chave.

Descarregar o percurso desde a fonte até ao ficheiro

Carregar exemplos do seu estilo

Envie um conjunto completo de um a três ficheiros. A Rapportly aplica os mesmos controlos de ficheiro e estilo do site. Armazenamento e créditos pertencem ao utilizador associado.

1. Envie ficheiros, nome, tipo de documento, âmbito pessoal ou equipa, confirmação explícita e identificador fixo. Estilos de equipa exigem administrador ou responsável de equipa.
2. Guarde o identificador de receção e consulte o estado. Recebido significa que o conjunto completo está guardado; revisão e aprovação podem seguir depois.
3. Após interrupção, repita exatamente o pedido sem criar um segundo estilo. Carregamentos incompletos podem ser repetidos durante trinta dias e depois são limpos de forma controlada.

Descarregar o guia multipart dos exemplos de estilo e erros

Ligar calendário ou caixa de correio

O utilizador dá pessoalmente consentimento na Google ou Microsoft. O software acompanha o pedido e pode terminar conscientemente a ligação. Palavras-passe e tokens do fornecedor não aparecem na resposta.

Use verbindingen:beheren para ligações e agenda:lezen para compromissos. O envio exige também permissão de envio e pedido explícito.

Guarde número do pedido, identificador e base atual. Repita exatamente pedidos perdidos; uma antiga desligação não pode remover uma ligação posterior.

A API pode escolher a caixa de correio predefinida com permissões de gestão e envio. Leia primeiro escolha e ligação atuais. Uma repetição antiga não altera uma escolha posterior; os envios existentes mantêm o remetente.

Descarregar passos de consentimento, compromissos, desligação e recuperação

Resultados de conversa a partir de texto

Envie uma transcrição com pelo menos cem caracteres. Acompanhe o resultado com gesprek_id. Opcionais: titel, tier, klantId e taal.

POST https://api.rapportly.io/api/rapportly/v1/gesprekken
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-gesprek-2026-0001
Content-Type: application/json

{
  "transcript": "Team Atlas bespreekt uitsluitend een fictieve oefening. Het team plant een training en verzamelt algemene voorbeeldvragen zonder klantgegevens.",
  "titel": "Kennismaking"
}

Ler variantes linguísticas existentes

Lê os resultados linguísticos existentes. As rotas de fluxo de trabalho descritas para iniciar, pausar, retomar e recuperar foram testadas localmente e em CI; o teste CRM em produção não verifica este processamento linguístico. Usa-as apenas num ambiente autorizado para esse fim. O utilizador, a chave, a fonte e os custos originais mantêm-se associados ao pedido. O estado atual da fonte, as permissões, o orçamento e a liquidação verificada continuam a ser necessários; uma fonte expirada ou eliminada não autoriza um novo início. O processamento em lote com um segundo idioma ativado continua bloqueado, incluindo com definições herdadas. O preenchimento pago de um único resultado de tradução em falta continua excluído.

GET https://api.rapportly.io/api/rapportly/v1/gesprekken/00000000-0000-4000-8000-000000000001/taalvarianten
Authorization: Bearer rply_<jouw_sleutel>

Receba um aviso quando o processamento terminar

A Rapportly pode enviar referências técnicas ao seu servidor. Obtenha depois o conteúdo com as permissões de leitura certas, sem consultar continuamente o progresso.

1. Crie um recetor HTTPS e registe-o por POST /webhooks com webhooks:beheren. Use a mesma chave de produção para os processamentos relevantes.
2. Verifique a assinatura nos bytes originais e guarde cada identificador de evento uma única vez. Confirme após guardar com segurança o aviso e a tarefa seguinte. Uma repetição não deve criar outro pedido.
3. Leia GET /webhook-afleveringen e os detalhes. A Rapportly repete falhas temporárias no máximo oito vezes; pode pedir uma ronda adicional. Aceite significa apenas recebido pelo seu servidor: confirme aí o processamento posterior.

• Descarregar o guia de webhooks, limites e recuperação
• Descarregar o exemplo Node.js para verificar assinaturas

O simulador não envia avisos reais. Teste o recetor com dados fictícios e integração de produção separada. O exemplo verifica o aviso; o seu servidor trata do armazenamento e das ações seguintes.

O que significa um código de erro?

Proteja a chave e os dados dos clientes

• Use a chave apenas no seu servidor, nunca em código público do navegador.
• Use uma chave por integração e revogue as antigas.
• Não coloque chaves, resultados ou ligações temporárias em registos ou conversas públicos.
• Guarde os dados obtidos segundo as regras de acesso do seu sistema.