Para desenvolvedores

API do Digiflow

Conecte o site, o aplicativo ou o ERP do seu cliente ao CRM. Chave com escopo, JSON dos dois lados e especificação OpenAPI para importar no Postman.

Especificação OpenAPI Ver os endpoints

Começando

Três passos até a primeira chamada

Escrita e leitura na mesma chave: o sistema de fora manda lead, evento e pedido, e consulta contatos, negócios, funis e agenda. Não existe parâmetro de conta na URL, a chave já diz de quem é o dado, e nunca enxerga outra conta.

Peça a chave ao administrador

Quem cria é o administrador da conta, no CRM, em Configurações → API. A chave começa com df_, pode ter validade e aparece uma vez só na tela: depois nem o suporte enxerga o valor.

A chave carrega os escopos marcados

Cada chave faz só o que foi liberado nela: leads:write, eventos:write, pedidos:write, contatos:read, negocios:read e agenda:read. Fora do escopo, 403. O administrador revoga e gera outra quando precisar.

Mande a primeira chamada

Todo endpoint aceita e responde JSON, com erro em português. Um lead de teste percorre o caminho inteiro, do POST até o card no funil.

Endereço e autenticação

Mande a chave no cabeçalho Authorization. Plataformas que não deixam editar esse cabeçalho podem usar X-Api-Key com o mesmo valor.

cabeçalhos

# Endereço base
https://app.digiflow.systems

Authorization: Bearer df_sua_chave
Content-Type: application/json

Importar no Postman

Import → Link com o endereço abaixo traz os endpoints com campos, exemplos e limites; falta só a chave. O mesmo arquivo serve para Insomnia, Swagger Editor e geradores de cliente.

OpenAPI 3.1

https://app.digiflow.systems/api/openapi.json

Referência

Endpoints

Integre sistemas externos ao CRM Digiflow.

API para sistemas externos mandarem informação para dentro do CRM: cadastrar lead de um formulário próprio e avisar que algo aconteceu com um lead que já existe, além de consultar contatos, negócios e agenda.

Todo endpoint é autenticado por uma chave de API da conta, criada pelo administrador em Configurações → API dentro do CRM ([app.digiflow.systems/config/api](https://app.digiflow.systems/config/api)). Só o administrador da conta cria a chave: quem desenvolve a integração pede a ele, com os escopos de que precisa. A chave aparece uma vez só, na hora de criar; guarde em lugar seguro. A chave identifica a conta: não existe parâmetro de conta na URL nem no corpo, e uma chave nunca enxerga dados de outra conta.

Escopos. Cada chave faz só o que o administrador marcou ao criá-la: leads:write (cadastrar leads), eventos:write (avisar acontecimentos), contatos:read, negocios:read e agenda:read (consultas). Chamar um endpoint sem o escopo devolve 403. A chave pode ter validade, e vencida devolve 401; revogada devolve 403.

Chave pessoal. Os escopos conversas:read, mensagens:read, tarefas:read e mensagens:send só existem numa chave de UMA pessoa, presa a canais escolhidos pelo administrador (o caso de um assistente que lê e responde o WhatsApp de alguém). Conversas, mensagens e envio ficam nos canais da chave; tarefas e agenda são as da pessoa. Chave com escopo pessoal sem a pessoa ou sem canal devolve 400. O envio passa pelas mesmas travas do inbox (janela de 24 h, número de quem responde, fila do WhatsApp Web) e tem limite próprio: 3 mensagens por contato e 20 por chave por dia, só das 8h às 22h de Brasília, com ref que nunca envia duas vezes.

Campos do contato. Para contatos:read, o administrador escolhe campo a campo o que a chave enxerga. Dado sensível (data de nascimento, anotações, campos customizados) fica fora por padrão: peça só o que a integração precisa (princípio do mínimo necessário da LGPD). Campos não liberados simplesmente não vêm na resposta.

Leitura. Listas são paginadas (page a partir de 1, limit até 200, padrão 50) e respondem { data, page, limit, total, has_more }. Use updated_since para sincronizar só o que mudou desde a última chamada. Limite: 120 chamadas por minuto por chave.

POST/api/webhooks/forms

Cadastrar ou atualizar um lead

Recebe o envio de um formulário externo e cria o contato no CRM, ou atualiza se ele já existir. O contato é procurado pelo telefone (chave única por conta) e, quando não vem telefone, pelo e-mail: mandar o mesmo lead duas vezes não duplica cadastro.

Contato novo entra sozinho na primeira etapa do funil principal, recebe um responsável pela regra de distribuição da conta, gera aviso no sino e dispara os gatilhos de automação form_submitted e contact_created. Contato que já existia e ainda não tinha negociação entra no funil do mesmo jeito; quem já tem negociação continua com ela (nunca duplica) e dispara só o form_submitted.

Origem: mande source quando souber. Se não mandar, a origem é deduzida dos parâmetros de rastreio (gclid vira Google Ads, fbclid vira Meta Ads, e assim por diante), o que costuma ser mais fiel do que o formulário adivinhar.

Limite: 30 chamadas por minuto por IP.

Corpo da requisição

Informe pelo menos telefone ou e-mail.

Campo	Tipo	O que é
`name`	texto	Nome de quem preencheu
`phone`	texto	Telefone em qualquer formato; o CRM normaliza para E.164. É a chave que evita duplicar.
`email`	e-mail	Usado para deduplicar quando não vem telefone
`source`	texto (lista fechada)	Origem do lead. Sem este campo, é deduzida do rastreio abaixo.`meta_ads_facebookmeta_ads_instagramgoogle_adslinkedin_adstiktok_adsmicrosoft_adswhatsappinstagramfacebooklinkedinsitechat_sitegoogle_organicogoogle_meu_negociomaterial_impressoassinatura_emailindicacaoformmanualplanilhaprospeccaoemail_inboundemail_marketingeventooutro`
`source_detail`	texto	Detalhe livre da origem: nome da campanha, do conjunto, do criativo.
`website`	texto	Site do contato ou da empresa dele. Fica gravado no cadastro.
`custom_fields`	objeto livre	Campos extras que vão para a ficha do contato. Precisam existir em Configurações → Campos customizados para aparecerem na tela.
`utm_source`	texto	Parâmetro de rastreio da página
`utm_medium`	texto	Parâmetro de rastreio da página
`utm_campaign`	texto	Vira o detalhe da origem quando source_detail não vem
`gclid`	texto	Identificador de clique do Google Ads
`wbraid`	texto	Usado pelo Google no lugar do gclid quando o iOS bloqueia o rastreio
`gbraid`	texto	Idem wbraid
`fbclid`	texto	Identificador de clique da Meta
`igshid`	texto	Identificador de clique do Instagram
`ttclid`	texto	Identificador de clique do TikTok
`page_url`	texto	Página onde o formulário estava
`referrer`	texto	Página de onde a pessoa veio

Como chamar

cURL

curl -X POST https://app.digiflow.systems/api/webhooks/forms \
  -H "Authorization: Bearer df_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria Silva",
  "phone": "(16) 99999-9999"
}'

JSON · Com origem e campos próprios

{
  "name": "Maria Silva",
  "phone": "(16) 99999-9999",
  "email": "maria@email.com",
  "source": "google_ads",
  "source_detail": "Campanha Institucional | Conjunto SP | Criativo 3",
  "custom_fields": {
    "interesse": "Plano anual",
    "score": 8
  }
}

JSON · Sem informar a origem, deixando o CRM deduzir

{
  "name": "Maria Silva",
  "phone": "(16) 99999-9999",
  "gclid": "Cj0KCQjw...",
  "utm_campaign": "institucional-sp",
  "page_url": "https://site-do-cliente.com.br/orcamento"
}

Respostas

201

Lead criado ou atualizado.

{
  "ok": true,
  "contact_id": "3f7c1a90-2b44-4f0e-9a1d-88c2b4e7d501"
}

400
Corpo inválido: falta telefone e e-mail, telefone impossível de normalizar, ou origem fora da lista.
```
{
  "error": "Informe pelo menos telefone ou e-mail"
}
```
401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```
429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

POST/api/webhooks/events

Avisar um acontecimento sobre um lead que já existe

Um sistema de fora avisa que algo aconteceu com um lead: terminou uma avaliação, assinou um documento, pagou, assistiu à aula. O que o CRM faz com isso é decisão da conta, montada em Automações: o gatilho Evento avisado por um sistema de fora casa pelo nome do evento e roda os passos escolhidos (mover de etapa, marcar tag, avisar alguém).

O nome do evento é combinado entre você e o cliente, e a comparação é exata, com maiúsculas e minúsculas contando. Se a automação espera avaliacao_concluida, mandar Avaliacao_Concluida não dispara nada.

Não cria contato de propósito. Quem cria lead é /api/webhooks/forms, que cuida de origem, deduplicação e distribuição de responsável. Evento sobre gente desconhecida volta 404 em vez de inventar meio cadastro.

Responde 200 mesmo quando nenhuma automação casa com o nome: do seu lado o aviso chegou, e o acontecimento fica registrado no histórico do contato de qualquer jeito.

Limite: 60 chamadas por minuto por IP.

Corpo da requisição

Informe o telefone ou o e-mail de quem o evento é.

Campo	Tipo	O que é
`event`obrigatório	texto	Nome curto e estável do acontecimento. Letras, números, ponto, hífen e sublinhado.
`phone`	texto	Procurado primeiro
`email`	e-mail	Usado quando o telefone não acha ninguém
`custom_fields`	objeto livre	O que o evento traz, somado à ficha do contato: resultado, nota, link do documento.

Como chamar

cURL

curl -X POST https://app.digiflow.systems/api/webhooks/events \
  -H "Authorization: Bearer df_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "avaliacao_concluida",
  "phone": "(16) 99999-9999",
  "custom_fields": {
    "resultado": "Apto",
    "nota": 82,
    "link_laudo": "https://exemplo.com/laudo/123"
  }
}'

Respostas

200

Evento registrado. Automações que casam com o nome já foram disparadas.

{
  "ok": true,
  "contact_id": "3f7c1a90-2b44-4f0e-9a1d-88c2b4e7d501",
  "event": "avaliacao_concluida"
}

400
Corpo inválido: nome de evento fora do padrão, ou nem telefone nem e-mail.
```
{
  "error": "Informe o telefone ou o e-mail de quem o evento é"
}
```
401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

404

Contato não existe nesta conta. Cadastre o lead primeiro.

{
  "error": "Contato não encontrado. Cadastre o lead primeiro em /api/webhooks/forms."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/contatos

Listar contatos

Lista os contatos da conta, do mais recente para o mais antigo por atualização. Só vêm os campos liberados na chave (escopo contatos:read); id, created_at e updated_at vêm sempre. Contato bloqueado como spam não aparece.

Para sincronizar, guarde o instante da última chamada e mande em updated_since.

Parâmetros

Parametro	Onde	Tipo	O que e
`q`	query string	texto	Busca por nome, telefone ou e-mail (contém)
`tag`	query string	texto	Só contatos com esta tag (nome exato, sem diferenciar maiúsculas)
`updated_since`	query string	data e hora (ISO 8601)	Só o que mudou depois deste instante (ISO 8601)
`page`	query string	número inteiro	Página, a partir de 1Padrao: `1`
`limit`	query string	número inteiro	Itens por página (máximo 200)Padrao: `50`

Como chamar

cURL

curl "https://app.digiflow.systems/api/v1/contatos?q=valor&tag=valor" \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Página de contatos.

{
  "data": [
    {
      "id": "3f1c...",
      "created_at": "2026-09-01T13:20:00Z",
      "updated_at": "2026-09-14T18:05:11Z",
      "name": "Maria Silva",
      "phone": "+5516999999999",
      "email": "maria@email.com",
      "company_name": "Padaria Central",
      "source": "google_ads",
      "source_detail": "Campanha Institucional",
      "tags": [
        "Cliente"
      ],
      "assigned_to": "Ana Martins"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "has_more": false
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

A chave não tem o escopo contatos:read.

{
  "error": "Esta chave não tem o escopo contatos:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/contatos/{id}

Ver um contato

Um contato pelo id, com os campos liberados na chave (escopo contatos:read).

Parâmetros

Parametro	Onde	Tipo	O que e
`id`obrigatorio	na URL	uuid	Id do contato (uuid)

Como chamar

cURL

curl https://app.digiflow.systems/api/v1/contatos/SEU_ID \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

O contato.

{
  "data": {
    "id": "3f1c...",
    "created_at": "2026-09-01T13:20:00Z",
    "updated_at": "2026-09-14T18:05:11Z",
    "name": "Maria Silva",
    "phone": "+5516999999999",
    "email": "maria@email.com",
    "company_name": "Padaria Central",
    "source": "google_ads",
    "source_detail": "Campanha Institucional",
    "tags": [
      "Cliente"
    ],
    "assigned_to": "Ana Martins"
  }
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

A chave não tem o escopo contatos:read.

{
  "error": "Esta chave não tem o escopo contatos:read. Peça ao administrador da conta para liberar."
}

404
Não existe contato com esse id nesta conta.
```
{
  "error": "Contato não encontrado"
}
```
429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/negocios

Listar negócios

Oportunidades (cards do funil) da conta, com funil, etapa, valor, situação e responsável (escopo negocios:read). O contato vem só como id e nome; o resto é do endpoint de contatos, que respeita os campos da chave. Negócio na lixeira não aparece.

Use /api/v1/funis para saber os ids de funil e etapa e filtrar.

Parâmetros

Parametro	Onde	Tipo	O que e
`status`	query string	texto (lista fechada)	Situação do negócio`openwonlost`
`pipeline_id`	query string	uuid	Só de um funil (id de /api/v1/funis)
`updated_since`	query string	data e hora (ISO 8601)	Só o que mudou depois deste instante (ISO 8601)
`page`	query string	número inteiro	Página, a partir de 1Padrao: `1`
`limit`	query string	número inteiro	Itens por página (máximo 200)Padrao: `50`

Como chamar

cURL

curl "https://app.digiflow.systems/api/v1/negocios?status=open&pipeline_id=valor" \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Página de negócios.

{
  "data": [
    {
      "id": "8a20...",
      "title": "Plano anual",
      "status": "open",
      "value": 4800,
      "contact": {
        "id": "3f1c...",
        "name": "Maria Silva"
      },
      "pipeline": {
        "id": "b7e1...",
        "name": "Vendas"
      },
      "stage": {
        "id": "c9d2...",
        "name": "Proposta",
        "entered_at": "2026-09-12T14:00:00Z"
      },
      "assigned_to": "Ana Martins",
      "lost_reason": null,
      "won_at": null,
      "lost_at": null,
      "created_at": "2026-09-01T13:20:00Z",
      "updated_at": "2026-09-12T14:00:00Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "has_more": false
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

A chave não tem o escopo negocios:read.

{
  "error": "Esta chave não tem o escopo negocios:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/funis

Listar funis e etapas

Os funis da conta com as etapas em ordem (escopo negocios:read). É o dicionário para interpretar os ids que vêm em /api/v1/negocios.

Como chamar

cURL

curl https://app.digiflow.systems/api/v1/funis \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Funis com etapas.

{
  "data": [
    {
      "id": "b7e1...",
      "name": "Vendas",
      "kind": "sales",
      "stages": [
        {
          "id": "c1..",
          "name": "Novo lead",
          "position": 0,
          "is_won": false,
          "is_lost": false,
          "role": null
        },
        {
          "id": "c9d2...",
          "name": "Proposta",
          "position": 3,
          "is_won": false,
          "is_lost": false,
          "role": null
        },
        {
          "id": "c5..",
          "name": "Ganhou",
          "position": 4,
          "is_won": true,
          "is_lost": false,
          "role": null
        }
      ]
    }
  ]
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

A chave não tem o escopo negocios:read.

{
  "error": "Esta chave não tem o escopo negocios:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/agenda

Listar compromissos

Compromissos da agenda da conta num intervalo (escopo agenda:read). Sem de/ate, devolve os próximos 30 dias. Na chave pessoal, só os da pessoa da chave; com external=1, junta os eventos do Google e do Outlook dela (o que o próprio Digiflow criou lá aparece uma vez só). Todo item diz a origem em source.

Parâmetros

Parametro	Onde	Tipo	O que e
`de`	query string	data e hora (ISO 8601)	Início do intervalo (ISO 8601). Padrão: agora
`ate`	query string	data e hora (ISO 8601)	Fim do intervalo (ISO 8601). Padrão: 30 dias depois de `de`
`status`	query string	texto (lista fechada)	Situação`confirmedcancelledcompletedno_show`
`member_id`	query string	uuid	Só de um profissional (na chave pessoal vale sempre a pessoa da chave)
`external`	query string	texto (lista fechada)	1 junta os eventos do Google e do Outlook da pessoa da chave, lidos na hora (só chave pessoal)`1`
`page`	query string	número inteiro	Página, a partir de 1Padrao: `1`
`limit`	query string	número inteiro	Itens por página (máximo 200)Padrao: `50`

Como chamar

cURL

curl "https://app.digiflow.systems/api/v1/agenda?de=2026-09-01T00:00:00Z&ate=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Página de compromissos, em ordem de horário.

{
  "data": [
    {
      "id": "d4f0...",
      "source": "digiflow",
      "title": "Reunião de proposta",
      "status": "confirmed",
      "starts_at": "2026-09-16T17:00:00.000Z",
      "ends_at": "2026-09-16T17:30:00.000Z",
      "all_day": false,
      "member": {
        "id": "m1..",
        "name": "Ana Martins"
      },
      "contact": {
        "id": "3f1c...",
        "name": "Maria Silva"
      },
      "opportunity_id": "8a20...",
      "meet_link": "https://meet.google.com/abc-defg-hij",
      "location": null,
      "created_at": "2026-09-10T10:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "has_more": false
}

400

external=1 numa chave que não é pessoal.

{
  "error": "external=1 precisa de uma chave pessoal (com a pessoa escolhida em Configurações → API)."
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

A chave não tem o escopo agenda:read, ou foi revogada.

{
  "error": "Esta chave não tem o escopo agenda:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/conversas

Listar conversas

Conversas dos canais da chave, da última mensagem mais recente para a mais antiga (escopo conversas:read). Contato na lixeira ou bloqueado como spam não aparece.

waiting=true traz só as que esperam a equipe, pela mesma regra do Flow do Início.

Parâmetros

Parametro	Onde	Tipo	O que e
`waiting`	query string	texto (lista fechada)	true: só as que esperam resposta; false: só as que não esperam`truefalse`
`since`	query string	data e hora (ISO 8601)	Só as com mensagem depois deste instante (ISO 8601)
`page`	query string	número inteiro	Página, a partir de 1Padrao: `1`
`limit`	query string	número inteiro	Itens por página (máximo 200)Padrao: `50`

Como chamar

cURL

curl "https://app.digiflow.systems/api/v1/conversas?waiting=true&since=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Página de conversas.

{
  "data": [
    {
      "id": "7b1e...",
      "contact": {
        "id": "3f1c...",
        "name": "Maria Silva",
        "phone": "+5516999999999"
      },
      "channel": {
        "id": "c0a1...",
        "type": "whatsapp",
        "name": "Comercial",
        "via": "web"
      },
      "assigned_to": {
        "id": "m1..",
        "name": "Ana Martins"
      },
      "status": "open",
      "unread_count": 1,
      "last_message_at": "2026-10-26T13:40:00.000Z",
      "last_inbound_at": "2026-10-26T13:40:00.000Z",
      "waiting": true,
      "waiting_minutes": 25,
      "needs_reply": true,
      "card_closed": false,
      "window_open": true,
      "preview": {
        "direction": "inbound",
        "text": "Consegue me mandar a proposta hoje?",
        "at": "2026-10-26T13:40:00.000Z"
      }
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "has_more": false
}

400

A chave tem escopo pessoal mas não tem a pessoa ou os canais.

{
  "error": "Esta chave tem escopo pessoal mas não tem a pessoa ou os canais. Crie a chave de novo em Configurações → API escolhendo a pessoa e os canais."
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada, sem o escopo conversas:read, ou a pessoa da chave não está mais ativa na conta.

{
  "error": "Esta chave não tem o escopo conversas:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/conversas/{id}/mensagens

Mensagens de uma conversa

As últimas limit mensagens antes de before, da mais antiga para a mais nova (escopo mensagens:read). Mensagem apagada não vem. Para ler mais para trás, mande em before a data da mais antiga que já veio.

Parâmetros

Parametro	Onde	Tipo	O que e
`id`obrigatorio	na URL	uuid	Id da conversa (uuid)
`limit`	query string	número inteiro	Quantas (padrão 40, máximo 200)Padrao: `40`
`before`	query string	data e hora (ISO 8601)	Só as anteriores a este instante (ISO 8601). Padrão: agora

Como chamar

cURL

curl "https://app.digiflow.systems/api/v1/conversas/SEU_ID/mensagens?before=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

As mensagens, em ordem de envio. `has_more` diz se há mais antigas.

{
  "data": [
    {
      "id": "a9d3...",
      "conversation_id": "7b1e...",
      "direction": "outbound",
      "content_type": "text",
      "body": "Mando ainda hoje, Maria!",
      "transcription": null,
      "created_at": "2026-10-26T13:45:00.000Z",
      "sent_by": "member",
      "member": {
        "id": "m1..",
        "name": "Ana Martins"
      }
    }
  ],
  "page": 1,
  "limit": 40,
  "total": 1,
  "has_more": false
}

400

A chave tem escopo pessoal mas não tem a pessoa ou os canais.

{
  "error": "Esta chave tem escopo pessoal mas não tem a pessoa ou os canais. Crie a chave de novo em Configurações → API escolhendo a pessoa e os canais."
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada, sem o escopo mensagens:read, ou a pessoa da chave não está mais ativa na conta.

{
  "error": "Esta chave não tem o escopo mensagens:read. Peça ao administrador da conta para liberar."
}

404

A conversa não existe nos canais desta chave.

{
  "error": "Conversa não encontrada nos canais desta chave.",
  "code": "conversa_nao_encontrada"
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/mensagens

Listar mensagens

Mensagens dos canais da chave num intervalo, em ordem de envio, cada uma com o contato (escopo mensagens:read). Serve, por exemplo, para ver o que a pessoa respondeu e a quê.

Parâmetros

Parametro	Onde	Tipo	O que e
`since`obrigatorio	query string	data e hora (ISO 8601)	Início do intervalo (ISO 8601)
`until`	query string	data e hora (ISO 8601)	Fim do intervalo (ISO 8601)
`direction`	query string	texto (lista fechada)	Só as que chegaram ou só as que saíram`inboundoutbound`
`conversation_id`	query string	uuid	Só de uma conversa
`page`	query string	número inteiro	Página, a partir de 1Padrao: `1`
`limit`	query string	número inteiro	Itens por página (máximo 200)Padrao: `50`

Como chamar

cURL

curl "https://app.digiflow.systems/api/v1/mensagens?since=2026-09-01T00:00:00Z&until=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Página de mensagens.

{
  "data": [
    {
      "id": "a9d3...",
      "conversation_id": "7b1e...",
      "direction": "outbound",
      "content_type": "text",
      "body": "Mando ainda hoje, Maria!",
      "transcription": null,
      "created_at": "2026-10-26T13:45:00.000Z",
      "sent_by": "member",
      "member": {
        "id": "m1..",
        "name": "Ana Martins"
      },
      "contact": {
        "id": "3f1c...",
        "name": "Maria Silva"
      }
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "has_more": false
}

400
since faltando ou inválido, direction inválida, ou chave pessoal sem pessoa ou canal.
```
{
  "error": "since é obrigatório (data ISO 8601)"
}
```
401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada, sem o escopo mensagens:read, ou a pessoa da chave não está mais ativa na conta.

{
  "error": "Esta chave não tem o escopo mensagens:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

POST/api/v1/mensagens

Enviar mensagem

Envia texto numa conversa que JÁ EXISTE nos canais da chave (escopo mensagens:send), pelo mesmo caminho do inbox: janela de 24 h da API oficial, número de quem responde, fila e travas do WhatsApp Web. A mensagem aparece no inbox como da pessoa da chave.

Limites da chave: 3 mensagens por contato e 20 por chave por dia, só das 8h às 22h (Brasília). A ref é sua chave de idempotência: repetir a mesma ref devolve o envio original (200, duplicate: true) sem mandar de novo. Um envio que falhou libera a ref para tentar outra vez.

Corpo da requisição

Campo	Tipo	O que é
`conversation_id`obrigatório	uuid
`text`obrigatório	texto
`ref`obrigatório	texto	Id único deste envio no seu sistema

Como chamar

cURL

curl -X POST https://app.digiflow.systems/api/v1/mensagens \
  -H "Authorization: Bearer df_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "7b1e...",
  "text": "Mando ainda hoje, Maria!",
  "ref": "rascunho-2026-10-26-0001"
}'

Respostas

200

A `ref` já tinha sido usada: o envio original, com `duplicate: true`. Nada foi enviado de novo.

{
  "message_id": "a9d3...",
  "status": "queued",
  "created_at": "2026-10-26T13:45:00.000Z",
  "duplicate": true
}

201

Enviado (ou na fila do WhatsApp Web).

{
  "message_id": "a9d3...",
  "status": "queued",
  "created_at": "2026-10-26T13:45:00.000Z",
  "duplicate": false
}

400
Corpo inválido, contato sem telefone, contato sem WhatsApp (o WhatsApp respondeu que o número não tem; fale por ligação), ou chave pessoal sem pessoa ou canal.
```
{
  "error": "ref precisa de pelo menos 8 caracteres"
}
```
401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada ou sem o escopo, ou o número é de outra pessoa da equipe (code canal_nao_permitido).

{
  "error": "Este número é de outra pessoa da equipe. Peça para ela responder, ou para o administrador.",
  "code": "canal_nao_permitido"
}

404

A conversa não existe nos canais desta chave.

{
  "error": "Conversa não encontrada nos canais desta chave.",
  "code": "conversa_nao_encontrada"
}

409

Janela de 24 h fechada na API oficial (code janela_fechada).

{
  "error": "Janela de 24h fechada. Envie um template aprovado.",
  "code": "janela_fechada"
}

423

Fora do horário de envio, das 8h às 22h de Brasília (code fora_do_horario).

{
  "error": "Pela API só sai mensagem das 8h às 22h (horário de Brasília).",
  "code": "fora_do_horario"
}

429
Limite do dia: 3 por contato (limite_do_contato) ou 20 por chave (limite_do_dia). Também é a resposta do limite de chamadas por minuto, sem code.
```
{
  "error": "Esta chave já enviou 20 mensagens hoje.",
  "code": "limite_do_dia"
}
```

503

O canal não está disponível agora: desligado, desconectado ou a Meta recusou (code canal_indisponivel).

{
  "error": "O número do WhatsApp Web está desconectado. Reconecte em Configurações > WhatsApp.",
  "code": "canal_indisponivel"
}

GET/api/v1/sign/modelos

Listar os modelos de envelope

Os modelos de envelope da conta (escopo sign:read), montados no Sign, aba Modelos: o documento, quem assina e onde. Use o id no envio.

Como chamar

cURL

curl https://app.digiflow.systems/api/v1/sign/modelos \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Os modelos.

{
  "data": [
    {
      "id": "c41d...",
      "nome": "Contrato de prestação",
      "documento": "office",
      "ativo": true,
      "vigencia_meses": 12,
      "renova_sozinho": false
    }
  ]
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada ou sem o escopo sign:read.

{
  "error": "Esta chave não tem o escopo sign:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

POST/api/v1/sign/envelopes

Mandar um documento para assinar

Cria o envelope a partir de um modelo de envelope ATIVO da conta (escopo sign:write), para um contato que já existe (pelo id, pelo telefone, com ou sem o nono dígito, ou pelo e-mail) e, por padrão, já envia o convite por e-mail. O contato precisa ter e-mail: é por ele que chegam o convite e o código de confirmação.

As regras são as mesmas da ação de automação "Enviar documento para assinar": o envelope sai em nome de quem criou o modelo, fica ligado ao negócio informado (ou ao card do contato) e o mesmo modelo não vai duas vezes para o mesmo negócio enquanto houver envelope aberto ou assinado (409). Modelo do Office é preenchido com os dados do contato e do negócio e ganha uma página de assinaturas no fim.

Para saber quando assinaram, cadastre um webhook de saída com o evento documento.assinado (ou consulte GET /api/v1/sign/envelopes/{id}). Limite: 30 chamadas por minuto por chave.

Corpo da requisição

Campo	Tipo	O que é
`modelo_id`obrigatório	uuid	O id de GET /api/v1/sign/modelos
`contato`obrigatório	objeto	Um dos três (nesta ordem de preferência)
`id`	uuid
`telefone`	texto
`email`	e-mail
`negocio_id`	uuid	Negócio do contato; sem ele, o card do contato
`enviar`	sim ou não	false deixa em rascunho no Sign para alguém conferir e enviarPadrão: `true`

Como chamar

cURL

curl -X POST https://app.digiflow.systems/api/v1/sign/envelopes \
  -H "Authorization: Bearer df_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
  "modelo_id": "c41d...",
  "contato": {
    "telefone": "+5516999999999"
  },
  "enviar": true
}'

Respostas

201

Envelope criado (e enviado, com `enviado: true`).

{
  "id": "8a2e...",
  "codigo": "7K3M-Q9TB-2HXR-PW4D",
  "status": "enviado",
  "enviado": true,
  "contato_id": "3f1c...",
  "negocio_id": "5b90...",
  "verificacao_url": "https://app.digiflow.systems/verificar/7K3M-Q9TB-2HXR-PW4D"
}

400

Corpo inválido.

{
  "error": "Informe contato.id, contato.telefone ou contato.email"
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada ou sem o escopo sign:write.

{
  "error": "Esta chave não tem o escopo sign:write. Peça ao administrador da conta para liberar."
}

404

Modelo, contato ou negócio não encontrado nesta conta.

{
  "error": "Contato não encontrado. Cadastre antes (POST /api/webhooks/forms) ou informe o id."
}

409

O modelo já tem um envelope aberto ou assinado para este negócio.

{
  "error": "Este modelo já tem um envelope aberto ou assinado para este contato."
}

422
Contato sem e-mail, modelo desligado ou incompleto, ou quem criou o modelo perdeu o acesso ao Sign.
```
{
  "error": "O contato não tem e-mail."
}
```
429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/sign/envelopes/{id}

Consultar um envelope

A situação do envelope (escopo sign:read), quem já assinou e a vigência do contrato. Não traz e-mail, IP nem a trilha: o documento lacrado fica no CRM e confere-se pela verificacao_url.

Parâmetros

Parametro	Onde	Tipo	O que e
`id`obrigatorio	na URL	uuid

Como chamar

cURL

curl https://app.digiflow.systems/api/v1/sign/envelopes/SEU_ID \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

O envelope.

{
  "id": "8a2e...",
  "codigo": "7K3M-Q9TB-2HXR-PW4D",
  "titulo": "Contrato de prestação - Maria Silva",
  "status": "enviado",
  "origem": "automacao",
  "modelo_id": "c41d...",
  "negocio_id": "5b90...",
  "criado_em": "2026-11-05T13:10:00Z",
  "enviado_em": "2026-11-05T13:10:02Z",
  "concluido_em": null,
  "recusado_em": null,
  "cancelado_em": null,
  "expirado_em": null,
  "prazo": "2026-11-20T13:10:00Z",
  "verificacao_url": "https://app.digiflow.systems/verificar/7K3M-Q9TB-2HXR-PW4D",
  "signatarios": [
    {
      "nome": "Maria Silva",
      "papel": "assina",
      "ordem": 1,
      "status": "pendente",
      "assinado_em": null,
      "recusado_em": null,
      "contato_id": "3f1c..."
    }
  ],
  "vigencia": {
    "inicio": null,
    "fim": null,
    "meses": 12,
    "renova_sozinho": false,
    "situacao": "aguardando_assinatura"
  }
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada ou sem o escopo sign:read.

{
  "error": "Esta chave não tem o escopo sign:read. Peça ao administrador da conta para liberar."
}

404

Envelope não encontrado nesta conta.

{
  "error": "Envelope não encontrado"
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

GET/api/v1/tarefas

Listar tarefas da pessoa

As tarefas em que a pessoa da chave é responsável, nos projetos que ela enxerga (escopo tarefas:read), prazo mais perto primeiro e sem prazo por último. Modelos e tarefas arquivadas não vêm.

Parâmetros

Parametro	Onde	Tipo	O que e
`status`	query string	texto (lista fechada)	open (padrão): só as abertas; all: todas`openall`Padrao: `open`
`due_until`	query string	data e hora (ISO 8601)	Só as com prazo até este instante (ISO 8601)
`page`	query string	número inteiro	Página, a partir de 1Padrao: `1`
`limit`	query string	número inteiro	Itens por página (máximo 200)Padrao: `50`

Como chamar

cURL

curl "https://app.digiflow.systems/api/v1/tarefas?status=open&due_until=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer df_sua_chave"

Respostas

200

Página de tarefas.

{
  "data": [
    {
      "id": "e2c4...",
      "title": "Revisar proposta",
      "description": null,
      "status": "open",
      "priority": "alta",
      "due_at": "2026-10-26T21:00:00.000Z",
      "completed_at": null,
      "overdue": false,
      "due_today": true,
      "parent_id": null,
      "board": {
        "id": "b1..",
        "name": "Equipe",
        "kind": "equipe"
      },
      "column": {
        "id": "k1..",
        "name": "Fazendo"
      },
      "subtasks": {
        "total": 3,
        "done": 1
      },
      "url": "https://app.digiflow.systems/tarefas/q/b1..?tarefa=e2c4..."
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "has_more": false
}

400

A chave tem escopo pessoal mas não tem a pessoa ou os canais.

{
  "error": "Esta chave tem escopo pessoal mas não tem a pessoa ou os canais. Crie a chave de novo em Configurações → API escolhendo a pessoa e os canais."
}

401
Chave ausente, inválida ou vencida.
```
{
  "error": "API key inválida"
}
```

403

Chave revogada, sem o escopo tarefas:read, ou a pessoa da chave não está mais ativa na conta.

{
  "error": "Esta chave não tem o escopo tarefas:read. Peça ao administrador da conta para liberar."
}

429
Limite de chamadas por minuto estourado. O cabeçalho Retry-After diz quantos segundos esperar.
```
{
  "error": "Muitas requisições"
}
```

Limites e erros

Cada endpoint tem um limite por minuto, indicado na referência. Ao estourar, a resposta é 429 com o cabeçalho Retry-After dizendo quantos segundos esperar.
Todo erro volta como { "error": "..." }, em português. Quando a recusa é de validação, vem junto detalhes, com o campo que caiu.
Reenvio é idempotente. O lead é procurado pelo telefone e o pedido pelo external_id: repetir uma janela de sincronização atualiza, não duplica.
Chave revogada, vencida ou fora do escopo responde 401 ou 403 na hora: é erro permanente, repetir não muda o resultado.
As listas vêm paginadas, em { data, page, limit, total, has_more }, e updated_since traz só o que mudou desde a última sincronização.

O caminho de volta

Para o CRM avisar o seu sistema quando algo acontece, hoje o caminho é a automação: o administrador monta a regra em Automações e escolhe a ação Chamar webhook, com a URL e um segredo. Serve para lead novo, mudança de etapa, negócio ganho e o resto dos gatilhos da conta.

Em desenvolvimento

Assinatura de eventos, com HMAC e reenvio automático, para o CRM chamar o seu endpoint sem depender de uma automação montada à mão. Se a sua integração precisa disso, escreve pra gente: avisamos quando entrar, e a fila leva em conta quem pediu.

Precisa de um endpoint que ainda não existe?

Conta o que a sua integração precisa ler ou escrever. A gente responde se já dá, se está na fila ou se vale construir junto.

Agendar demonstração Falar no WhatsApp

7 dias grátis, sem fidelidade. Implantação opcional com a nossa equipe.