Wizer APIDocumentação v1
Baixar OpenAPI JSON
API pública Bearer token OpenAPI 3.1 JSON para Swagger, Postman e ferramentas compatíveis

API Publica do Wizer#

Documentacao da API publica baseada na implementacao atual.

Visao geral#

Essa API expoe recursos da organizacao via Bearer token gerado no Hub de Integracoes.

Regras principais:

  • Cada token pertence a uma unica organizacao.
  • Cada organizacao pode ter ate 3 tokens ativos.
  • O token e exibido apenas uma vez no momento da criacao.
  • Requisicoes da API publica sempre operam dentro da organizacao do token.
  • O Hub de Integracoes usa autenticacao interna de dashboard, nao o token publico.

Base URLs#

  • Backend base: /api/v1
  • API publica: /api/v1/public-api

Autenticacao#

Header obrigatorio#

Todas as rotas publicas exigem:

HTTP
Authorization: Bearer <public-api-token>

Padroes de resposta#

Erros#

  • 400 Bad Request: validacao falhou
  • 401 Unauthorized: token ausente, invalido ou revogado
  • 403 Forbidden: operacao nao permitida para a organizacao
  • 404 Not Found: registro nao encontrado na organizacao autenticada
  • 409 Conflict: conflito de negocio, como excesso de tokens ativos ou revisao desatualizada de configuracao de agente

Regras de escopo#

Quando um endpoint e public API:

  • id sempre e interpretado no contexto da organizacao do token
  • nao existe acesso cruzado entre organizacoes
  • os dados retornados seguem os contratos publicos descritos nesta documentacao
  • organizationId e removido das respostas da API publica
  • contatos nao retornam avatarUrl; nas identidades de resposta, somente id e channelType sao expostos. Campos internos de provedor, tipo de identidade, identificadores normalizados e dados da conexao nao fazem parte do contrato publico

Validacao de WhatsApp no cadastro#

  • POST /api/v1/public-api/contacts verifica se phoneNumber e primaryContactWhatsapp possuem WhatsApp antes de salvar.
  • PATCH /api/v1/public-api/contacts/:id aplica a mesma verificacao aos campos de WhatsApp enviados.
  • POST /api/v1/public-api/opportunities, quando cria um contato embutido sem contactId, verifica se contact.phoneNumber possui WhatsApp antes de gravar o contato e a oportunidade. Usar um contato existente nao repete a verificacao.
  • Se a verificacao confirmar que o numero nao possui WhatsApp, a requisicao retorna 400 Bad Request e nao grava o cadastro.
  • Se nao for possivel concluir a verificacao de WhatsApp, o cadastro prossegue com o telefone normalizado, sem confirmacao.
  • Quando a verificacao retorna um numero canonico de WhatsApp, esse numero e utilizado no cadastro. O telefone secundario nao recebe essa verificacao.

Resumo dos endpoints#

Metodo Rota Autenticacao Descricao
GET /api/v1/public-api/tags Bearer Lista tags da organizacao
GET /api/v1/public-api/tags/:id Bearer Consulta tag por id
POST /api/v1/public-api/tags Bearer Cria tag
PATCH /api/v1/public-api/tags/:id Bearer Atualiza tag
DELETE /api/v1/public-api/tags/:id Bearer Exclui tag, com remocao explicita das associacoes
GET /api/v1/public-api/contacts Bearer Lista contatos
GET /api/v1/public-api/contacts/:id Bearer Consulta contato por id
GET /api/v1/public-api/contacts/:id/tags Bearer Lista tags do contato
POST /api/v1/public-api/contacts/:id/tags Bearer Adiciona tag ao contato
PUT /api/v1/public-api/contacts/:id/tags Bearer Substitui todas as tags do contato
DELETE /api/v1/public-api/contacts/:id/tags/:tagId Bearer Remove tag do contato
POST /api/v1/public-api/contacts Bearer Cria contato
PATCH /api/v1/public-api/contacts/:id Bearer Atualiza contato
DELETE /api/v1/public-api/contacts/:id Bearer Exclui contato
GET /api/v1/public-api/opportunities Bearer Lista oportunidades
GET /api/v1/public-api/opportunities/:id Bearer Consulta oportunidade por id
POST /api/v1/public-api/opportunities Bearer Cria oportunidade
PATCH /api/v1/public-api/opportunities/:id Bearer Atualiza oportunidade
DELETE /api/v1/public-api/opportunities/:id Bearer Exclui oportunidade
GET /api/v1/public-api/users Bearer Lista usuarios
GET /api/v1/public-api/users/:id Bearer Consulta usuario por id
GET /api/v1/public-api/tasks/statuses Bearer (tasks:read) Lista status ativos de tarefas
GET /api/v1/public-api/tasks Bearer (tasks:read) Lista tarefas paginadas e filtradas
GET /api/v1/public-api/tasks/:taskId Bearer (tasks:read) Consulta tarefa e dados relacionados
POST /api/v1/public-api/tasks Bearer (tasks:write) Cria tarefa
PATCH /api/v1/public-api/tasks/:taskId Bearer (tasks:write) Atualiza tarefa
POST /api/v1/public-api/tasks/:taskId/comments Bearer (tasks:write) Adiciona comentario
POST /api/v1/public-api/tasks/:taskId/participants Bearer (tasks:write) Adiciona participante
DELETE /api/v1/public-api/tasks/:taskId/participants/:userId Bearer (tasks:write) Remove participante
POST /api/v1/public-api/tasks/:taskId/conversations Bearer (tasks:write) Vincula conversa
GET /api/v1/public-api/conversations Bearer (conversations:read) Lista conversas por organização
GET /api/v1/public-api/conversations/:conversationId Bearer (conversations:read) Consulta resumo da conversa
GET /api/v1/public-api/conversations/:conversationId/messages Bearer (conversations:read) Lista mensagens da conversa
GET /api/v1/public-api/catalog/items Bearer Lista itens do catalogo
GET /api/v1/public-api/catalog/items/:itemId Bearer Consulta item do catalogo
POST /api/v1/public-api/catalog/items Bearer Cria item do catalogo
PATCH /api/v1/public-api/catalog/items/:itemId Bearer Atualiza item do catalogo
GET /api/v1/public-api/sales Bearer Lista vendas
POST /api/v1/public-api/sales Bearer Cria venda
GET /api/v1/public-api/sales/:saleId Bearer Consulta venda
PATCH /api/v1/public-api/sales/:saleId Bearer Atualiza venda
POST /api/v1/public-api/sales/:saleId/cancel Bearer Cancela venda
POST /api/v1/public-api/sales/:saleId/complete Bearer Conclui venda
POST /api/v1/public-api/sales/:saleId/confirm Bearer Confirma venda
GET /api/v1/public-api/sales/:saleId/operations Bearer Lista operações financeiras e de fulfillment
POST /api/v1/public-api/sales/:saleId/charge-groups Bearer Cria grupo de cobrança
POST /api/v1/public-api/sales/:saleId/fulfillments Bearer Cria fulfillment
GET /api/v1/public-api/sales/:saleId/checkouts Bearer Lista checkouts
POST /api/v1/public-api/sales/:saleId/checkouts Bearer Cria checkout Asaas
POST /api/v1/public-api/sales/:saleId/payments Bearer Registra pagamento
POST /api/v1/public-api/commercial/pre-checkout-intents Bearer (checkout_intents:write) Registra início anônimo de pré-checkout
POST /api/v1/public-api/commercial/pre-checkout-intents/complete Bearer (checkout_intents:write) Completa pré-checkout com dados do contato
GET /api/v1/public-api/commercial/pre-checkout-intents/:intentId Bearer (checkout_intents:read) Consulta estado e vínculos da intenção
GET /api/v1/public-api/commissions Bearer Lista lançamentos de comissão
GET /api/v1/public-api/financial/categories Bearer Lista categorias financeiras ativas
GET /api/v1/public-api/financial/entries Bearer Lista lancamentos financeiros
GET /api/v1/public-api/financial/entries/:entryId Bearer Consulta lancamento financeiro
POST /api/v1/public-api/financial/entries Bearer Cria lancamento financeiro
PATCH /api/v1/public-api/financial/entries/:entryId Bearer Atualiza lancamento financeiro manual
POST /api/v1/public-api/financial/entries/:entryId/settle Bearer Registra baixa total ou parcial

1) Tags#

As tags sao compartilhadas por todos os contatos da organizacao do token. Todas as operacoes abaixo exigem Authorization: Bearer <public-api-token> e ignoram registros de outras organizacoes.

1.1 Listar tags#

  • Metodo: GET
  • Rota: /api/v1/public-api/tags
  • Autenticacao: Bearer token

Parametros de query

Campo Tipo Obrigatorio Descricao
search string Nao Busca por nome ou descricao
limit number Nao Quantidade maxima. Padrao 20, minimo 1, maximo 100
offset number Nao Deslocamento. Padrao 0, minimo 0

Exemplo de resposta

JSON
{
  "data": [
    {
      "id": "tag-1",
      "name": "Cliente VIP",
      "description": "Contatos prioritarios",
      "color": "#00a884",
      "bg": "#00a884/10",
      "createdAt": "2026-07-15T12:00:00.000Z",
      "updatedAt": "2026-07-15T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "offset": 0,
    "totalPages": 1
  }
}

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/tags?search=exemplo&limit=20" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

1.2 Consultar tag por id#

  • Metodo: GET
  • Rota: /api/v1/public-api/tags/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID da tag.

O retorno e um objeto de tag com os campos mostrados na listagem.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/tags/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Exemplo",
  "description": "Descricao de exemplo",
  "color": "#FF7A1A",
  "bg": "#FF7A1A/10",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z"
}

1.3 Criar tag#

  • Metodo: POST
  • Rota: /api/v1/public-api/tags
  • Autenticacao: Bearer token

Parametros de body

Campo Tipo Obrigatorio Descricao
name string Sim Nome da tag. Maximo 120 caracteres
description string Sim Descricao. Maximo 255 caracteres
color string Sim Cor principal. Maximo 20 caracteres
bg string Sim Cor de fundo. Maximo 20 caracteres

O nome e normalizado com trim e convertido para minusculas para verificar unicidade dentro da organizacao. Nomes duplicados retornam 409 Conflict.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/tags" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Exemplo",
  "description": "Descricao de exemplo",
  "color": "#FF7A1A",
  "bg": "#FF7A1A/10"
}'

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Exemplo",
  "description": "Descricao de exemplo",
  "color": "#FF7A1A",
  "bg": "#FF7A1A/10",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z"
}

1.4 Atualizar tag#

  • Metodo: PATCH
  • Rota: /api/v1/public-api/tags/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID da tag.

Parametros de body

Campo Tipo Obrigatorio Descricao
name string Nao Campo name. Maximo de caracteres 120
description string Nao Campo description. Maximo de caracteres 255
color string Nao Campo color. Maximo de caracteres 20
bg string Nao Campo bg. Maximo de caracteres 20

Todos os campos de criacao sao opcionais no PATCH. O ID e sempre limitado a organizacao do token.

Exemplo de requisicao

BASH
curl -X PATCH "https://api.wizer.digital/api/v1/public-api/tags/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Exemplo"
}'

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Exemplo",
  "description": "Descricao de exemplo",
  "color": "#FF7A1A",
  "bg": "#FF7A1A/10",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z"
}

1.5 Excluir tag#

  • Metodo: DELETE
  • Rota: /api/v1/public-api/tags/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID da tag.

Parametros de query

Campo Tipo Obrigatorio Descricao
removeFromContacts boolean Nao Remove explicitamente todas as associações antes de excluir. Padrao false

Por seguranca, uma tag associada a contatos nao pode ser excluida implicitamente. Nesse caso, a API retorna 409 Conflict.

Exemplo de requisicao

BASH
curl -X DELETE "https://seu-dominio.com/api/v1/public-api/tags/tag-1?removeFromContacts=true" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "success": true,
  "removedAssignmentCount": 42
}

As operacoes a seguir gerenciam as tags associadas a um contato da mesma organizacao.

1.6 Listar tags do contato#

  • Metodo: GET
  • Rota: /api/v1/public-api/contacts/:id/tags
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do contato.

Retorna um array de objetos de tag. Se o contato nao existir na organizacao do token, retorna 404 Not Found.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/contacts/11111111-1111-4111-8111-111111111111/tags" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Exemplo",
    "description": "Descricao de exemplo",
    "color": "#FF7A1A",
    "bg": "#FF7A1A/10",
    "createdAt": "2026-10-07T12:00:00.000Z",
    "updatedAt": "2026-10-07T12:00:00.000Z"
  }
]

1.7 Adicionar tag ao contato#

  • Metodo: POST
  • Rota: /api/v1/public-api/contacts/:id/tags
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do contato.

Parametros de body

Campo Tipo Obrigatorio Descricao
tagId UUID Sim UUID da tag da mesma organizacao.

tagId deve ser um UUID de uma tag da mesma organizacao. A operacao e idempotente: associar uma tag ja associada nao cria duplicidade e retorna created: false.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/contacts/11111111-1111-4111-8111-111111111111/tags" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "tagId": "11111111-1111-4111-8111-111111111111"
}'

Exemplo de resposta

JSON
{
  "created": true
}

1.8 Remover tag do contato#

  • Metodo: DELETE
  • Rota: /api/v1/public-api/contacts/:id/tags/:tagId
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do contato.
tagId string Sim ID da tag.

Retorna { "removed": true }. Se a tag nao estiver associada ao contato, retorna 404 Not Found.

Exemplo de requisicao

BASH
curl -X DELETE "https://api.wizer.digital/api/v1/public-api/contacts/11111111-1111-4111-8111-111111111111/tags/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "removed": true
}

1.9 Substituir todas as tags do contato#

  • Metodo: PUT
  • Rota: /api/v1/public-api/contacts/:id/tags
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do contato.

Parametros de body

Campo Tipo Obrigatorio Descricao
tagIds UUID[] Sim UUIDs das tags que devem permanecer associadas.

tagIds deve ser um array de UUIDs. O array representa o estado final desejado: tags ausentes sao removidas, tags novas sao adicionadas e IDs repetidos sao ignorados. Para remover todas as tags, envie tagIds: [].

Exemplo de requisicao

BASH
curl -X PUT "https://api.wizer.digital/api/v1/public-api/contacts/11111111-1111-4111-8111-111111111111/tags" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "tagIds": [
    "11111111-1111-4111-8111-111111111111"
  ]
}'

Exemplo de resposta

JSON
{}

2) Contatos#

2.1 Listar contatos#

  • Metodo: GET
  • Rota: /api/v1/public-api/contacts
  • Autenticacao: Bearer token

Parametros de query

Campo Tipo Obrigatorio Descricao
search string Nao Filtra por texto livre
limit number Nao Quantidade maxima de registros. Minimo 1, maximo 200
offset number Nao Deslocamento da pagina. Minimo 0
contactType all | PF | PJ Nao Filtra por tipo de contato
channelType string Nao Filtra por tipo de canal
conversationState all | with_conversations | without_conversations Nao Filtra pela existencia de conversas
assigneeId string Nao Filtra por responsavel do contato
teamId string Nao Filtra por time
aiPausedState all | active | paused Nao Filtra pelo estado de pausa do agente de IA
contactTagIds string[] Nao IDs de tags associadas diretamente ao contato. Aceita array ou string separada por virgula; exige todas as tags informadas, inclusive em contatos sem conversa
inactiveSinceDays number Nao Contatos inativos ha X dias. Minimo 1
opportunityStatus all | open | won | lost Nao Filtra pelo status das oportunidades vinculadas
pipelineId string Nao Filtra por pipeline
stageId string Nao Filtra por etapa
minValue number Nao Valor minimo de oportunidade vinculada
maxValue number Nao Valor maximo de oportunidade vinculada
opportunityTemperature all | cold | warm | hot Nao Filtra por temperatura da oportunidade
opportunityOwnerId string Nao Filtra pelo dono da oportunidade
lostReasonId string Nao Filtra por motivo de perda da oportunidade

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/contacts?search=Maria&limit=20&offset=0&contactType=PF" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "data": [
    {
      "id": "contact-1",
      "name": "Maria Souza",
      "email": "[email protected]",
      "phoneNumber": "5511999999999",
      "contactType": "PF",
      "documentNumber": null,
      "primaryContactName": null,
      "primaryContactWhatsapp": null,
      "metadata": {},
      "createdAt": "2026-06-17T12:00:00.000Z",
      "updatedAt": "2026-06-17T12:00:00.000Z"
    }
  ]
}

Observacao: a implementacao atual do adaptador da API publica retorna somente data. Embora o servico interno calcule pagination, filters, metrics e availableChannels, esses campos nao sao repassados por esta rota.

O filtro contactTagIds consulta as tags do contato independentemente de conversas. Para listar contatos por tag em paginas, use limit (ate 200) e avance offset ate a pagina retornar data: []. Use conversationState apenas quando quiser filtrar explicitamente pela existencia de conversas.

2.2 Consultar contato por id#

  • Metodo: GET
  • Rota: /api/v1/public-api/contacts/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do contato

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/contacts/contact-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "id": "contact-1",
  "name": "Maria Souza",
  "email": "[email protected]",
  "phoneNumber": "5511999999999",
  "contactType": "PF",
  "documentNumber": null,
  "primaryContactName": null,
  "primaryContactWhatsapp": null,
  "metadata": {},
  "identities": [
    {
      "id": "identity-1",
      "channelType": "whatsapp"
    }
  ],
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z"
}

2.3 Criar contato#

  • Metodo: POST
  • Rota: /api/v1/public-api/contacts
  • Autenticacao: Bearer token

Parametros de body

Campo Tipo Obrigatorio Descricao
name string Sim Nome do contato
email string Nao E-mail do contato
phoneNumber string Nao Telefone do contato
avatarUrl string Nao URL do avatar
contactType PF | PJ Nao Tipo do contato
documentNumber string Nao CPF/CNPJ ou outro documento
primaryContactName string Nao Nome do contato principal, usado em PJ
primaryContactWhatsapp string Nao WhatsApp do contato principal
metadata object Nao Objeto livre com metadados
identities array Nao Identidades de canal vinculadas ao contato

identities

Cada item do array possui:

Campo Tipo Obrigatorio Descricao
id string Nao ID da identidade, se ja existir
connectionId string Sim ID da conexao/canal
channelType string Sim Tipo do canal, ex.: whatsapp, instagram
identifier string Sim Identificador da identidade no canal

Exemplo de requisicao

BASH
curl -X POST "https://seu-dominio.com/api/v1/public-api/contacts" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "[email protected]",
    "phoneNumber": "5511999999999",
    "contactType": "PF",
    "metadata": {
      "origem": "n8n"
    },
    "identities": [
      {
        "connectionId": "connection-1",
        "channelType": "whatsapp",
        "identifier": "5511999999999"
      }
    ]
  }'

Exemplo de resposta

JSON
{
  "id": "contact-1",
  "name": "Maria Souza",
  "email": "[email protected]",
  "phoneNumber": "5511999999999",
  "contactType": "PF",
  "documentNumber": null,
  "primaryContactName": null,
  "primaryContactWhatsapp": null,
  "metadata": {
    "origem": "n8n"
  },
  "identities": [
    {
      "id": "identity-1",
      "channelType": "whatsapp"
    }
  ],
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z"
}

2.4 Atualizar contato#

  • Metodo: PATCH
  • Rota: /api/v1/public-api/contacts/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do contato

Os mesmos campos do POST /contacts, todos opcionais:

Parametros de body

Campo Tipo Obrigatorio Descricao
name string Nao Novo nome
email string Nao Novo e-mail
phoneNumber string Nao Novo telefone
avatarUrl string Nao Nova URL do avatar
contactType PF | PJ Nao Novo tipo
documentNumber string Nao Novo documento
primaryContactName string Nao Novo nome do contato principal
primaryContactWhatsapp string Nao Novo WhatsApp do contato principal
metadata object Nao Metadados adicionais
identities array Nao Nova lista de identidades

Exemplo de requisicao

BASH
curl -X PATCH "https://seu-dominio.com/api/v1/public-api/contacts/contact-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Maria Souza da Silva",
    "metadata": {
      "origem": "erp"
    }
  }'

Exemplo de resposta

JSON
{
  "id": "contact-1",
  "name": "Maria Souza da Silva",
  "email": "[email protected]",
  "phoneNumber": "5511999999999",
  "contactType": "PF",
  "metadata": {
    "origem": "erp"
  },
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:10:00.000Z"
}

2.5 Excluir contato#

  • Metodo: DELETE
  • Rota: /api/v1/public-api/contacts/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do contato

Exemplo de requisicao

BASH
curl -X DELETE "https://seu-dominio.com/api/v1/public-api/contacts/contact-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "success": true
}

3) Oportunidades#

3.1 Listar oportunidades#

  • Metodo: GET
  • Rota: /api/v1/public-api/opportunities
  • Autenticacao: Bearer token

Parametros de query

Campo Tipo Obrigatorio Descricao
pipelineId string Nao Filtra por pipeline
ownerUserId string Nao Filtra por dono
stageId string Nao Filtra por etapa
search string Nao Busca livre por titulo ou empresa
status open | won | lost | all Nao Filtra pelo status
archived exclude | include | only Nao Filtra oportunidades arquivadas
limit number Nao Quantidade maxima de registros. Minimo 1, maximo efetivo 100
offset number Nao Deslocamento da pagina. Minimo 0

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/opportunities?status=open&limit=20&offset=0" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "data": [
    {
      "id": "opp-1",
      "contactId": "contact-1",
      "pipelineId": "pipeline-1",
      "stageId": "stage-1",
      "ownerUserId": "user-1",
      "teamId": null,
      "title": "Nova oportunidade",
      "companyName": "Empresa Exemplo",
      "status": "open",
      "value": 1500,
      "currencyCode": "BRL",
      "createdAt": "2026-06-17T12:00:00.000Z",
      "updatedAt": "2026-06-17T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "offset": 0,
    "totalPages": 1
  }
}

3.2 Consultar oportunidade por id#

  • Metodo: GET
  • Rota: /api/v1/public-api/opportunities/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID da oportunidade

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/opportunities/opp-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "id": "opp-1",
  "contactId": "contact-1",
  "pipelineId": "pipeline-1",
  "stageId": "stage-1",
  "ownerUserId": "user-1",
  "teamId": null,
  "createdByUserId": "user-2",
  "createdSource": "dashboard",
  "sourceConversationId": null,
  "title": "Nova oportunidade",
  "companyName": "Empresa Exemplo",
  "contactRole": "Decisor",
  "source": "site",
  "status": "open",
  "value": 1500,
  "currencyCode": "BRL",
  "probability": 50,
  "priority": "medium",
  "temperature": "warm",
  "health": "healthy",
  "summary": "Resumo da oportunidade",
  "expectedCloseAt": null,
  "nextActionAt": null,
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z"
}

3.3 Criar oportunidade#

  • Metodo: POST
  • Rota: /api/v1/public-api/opportunities
  • Autenticacao: Bearer token

Parametros de body

Campo Tipo Obrigatorio Descricao
contactId string Condicional ID do contato existente. Se nao enviar, o objeto contact deve ser enviado
contact object Condicional Contato embutido para criar o contato junto
pipelineId string Nao ID do pipeline
stageId string Nao ID da etapa
ownerUserId string Nao ID do usuario dono da oportunidade
sourceConversationId string Nao ID da conversa de origem
createdSource dashboard | chat_manual | ai_agent | flow Nao Origem de criacao
title string Nao Titulo da oportunidade
companyName string Nao Nome da empresa
contactRole string Nao Papel do contato
source string Nao Origem comercial
value number Nao Valor monetario
currencyCode string Nao Codigo da moeda, ex.: BRL
probability number Nao Probabilidade comercial
probabilityMode auto | manual Nao Modo da probabilidade
score number Nao Score comercial entre 0 e 100
priority low | medium | high | urgent Nao Prioridade
temperature cold | warm | hot Nao Temperatura do negocio
health healthy | at_risk | stalled Nao Saude do negocio
summary string Nao Resumo livre
tags string[] Nao Lista de tags
nextActionAt string (ISO) Nao Proxima acao
expectedCloseAt string (ISO) Nao Previsao de fechamento
closingNotes string Nao Observacoes de fechamento
metadata object Nao Metadados livres

contact

Quando usar contato embutido:

Campo Tipo Obrigatorio Descricao
name string Sim Nome do contato a criar
email string Nao E-mail do contato
phoneNumber string Nao Telefone do contato
metadata object Nao Metadados do contato

Exemplo de requisicao

BASH
curl -X POST "https://seu-dominio.com/api/v1/public-api/opportunities" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "contactId": "contact-1",
    "pipelineId": "pipeline-1",
    "stageId": "stage-1",
    "title": "Nova oportunidade",
    "companyName": "Empresa Exemplo",
    "value": 1500,
    "currencyCode": "BRL",
    "priority": "medium",
    "temperature": "warm",
    "metadata": {
      "origem": "n8n"
    }
  }'

Exemplo de resposta

JSON
{
  "id": "opp-1",
  "contactId": "contact-1",
  "pipelineId": "pipeline-1",
  "stageId": "stage-1",
  "ownerUserId": "user-1",
  "title": "Nova oportunidade",
  "companyName": "Empresa Exemplo",
  "status": "open",
  "value": 1500,
  "currencyCode": "BRL",
  "probability": 50,
  "priority": "medium",
  "temperature": "warm",
  "health": "healthy",
  "metadata": {
    "origem": "n8n"
  },
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z"
}

3.4 Atualizar oportunidade#

  • Metodo: PATCH
  • Rota: /api/v1/public-api/opportunities/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID da oportunidade

Todos os campos de criacao tambem podem ser enviados neste endpoint, alem dos campos de controle abaixo:

Parametros de body

Campo Tipo Obrigatorio Descricao
status open | won | lost Nao Novo status
lostReasonId string Nao ID do motivo de perda
lostReasonText string Nao Texto livre do motivo de perda
archived boolean Nao Arquivar ou desarquivar a oportunidade

Exemplo de requisicao

BASH
curl -X PATCH "https://seu-dominio.com/api/v1/public-api/opportunities/opp-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": "won",
    "value": 2500,
    "summary": "Negocio fechado com sucesso"
  }'

Exemplo de resposta

JSON
{
  "id": "opp-1",
  "contactId": "contact-1",
  "pipelineId": "pipeline-1",
  "stageId": "stage-2",
  "ownerUserId": "user-1",
  "title": "Nova oportunidade",
  "status": "won",
  "value": 2500,
  "probability": 100,
  "archivedAt": null,
  "updatedAt": "2026-06-17T12:10:00.000Z"
}

3.5 Excluir oportunidade#

  • Metodo: DELETE
  • Rota: /api/v1/public-api/opportunities/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID da oportunidade

Exemplo de requisicao

BASH
curl -X DELETE "https://seu-dominio.com/api/v1/public-api/opportunities/opp-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "success": true
}

4) Usuarios#

Os endpoints de usuarios da API publica sao somente leitura. Criacao, atualizacao e exclusao de usuarios nao sao expostas pela API publica.

O token so pode listar ou consultar usuarios pertencentes a mesma organizacao vinculada ao token. IDs de usuarios de outras organizacoes sao tratados como nao encontrados.

4.1 Listar usuarios#

  • Metodo: GET
  • Rota: /api/v1/public-api/users
  • Autenticacao: Bearer token

Parametros de query

Campo Tipo Obrigatorio Descricao
page number Nao Pagina desejada. Padrao 1
limit number Nao Itens por pagina. Minimo 1, maximo 100
search string Nao Busca por nome ou e-mail

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/users?page=1&limit=20&search=ana" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "data": [
    {
      "id": "user-1",
      "name": "Ana Silva",
      "email": "[email protected]",
      "bio": null,
      "profileLinks": [],
      "whatsapp": "11999999999",
      "avatarKey": null,
      "avatarUrl": "https://cdn.exemplo.com/avatar.png",
      "role": "org-admin",
      "roleDisplayName": "Org Admin",
      "roleMaskId": null,
      "isActive": true,
      "emailVerified": true,
      "authProvider": "local",
      "teams": [],
      "managedTeams": [],
      "createdAt": "2026-06-17T12:00:00.000Z",
      "updatedAt": "2026-06-17T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

4.2 Consultar usuario por id#

  • Metodo: GET
  • Rota: /api/v1/public-api/users/:id
  • Autenticacao: Bearer token

Parametros de path

Campo Tipo Obrigatorio Descricao
id string Sim ID do usuario

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/users/user-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "id": "user-1",
  "name": "Ana Silva",
  "email": "[email protected]",
  "bio": null,
  "profileLinks": [],
  "whatsapp": "11999999999",
  "avatarKey": null,
  "avatarUrl": "https://cdn.exemplo.com/avatar.png",
  "role": "org-admin",
  "roleDisplayName": "Org Admin",
  "roleMaskId": null,
  "isActive": true,
  "emailVerified": true,
  "authProvider": "local",
  "teams": [],
  "managedTeams": [],
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z"
}

5) Modulo comercial#

A API publica do modulo comercial expoe 18 operacoes para catalogo, vendas, cobrancas, entregas, pagamentos, checkouts e comissoes.

Todas as rotas usam Authorization: Bearer <public-api-token>. Alem do escopo correto, as operacoes comerciais exigem que o token esteja associado a um usuario ativo da organizacao. As permissoes e restricoes desse usuario continuam sendo respeitadas.

Escopos comerciais#

Escopo Operacoes permitidas
catalog:read Listar e consultar itens do catalogo
catalog:write Criar e atualizar itens do catalogo
sales:read Listar e consultar vendas, operacoes e checkouts
sales:write Criar, atualizar, confirmar, concluir e cancelar vendas; criar grupos de cobranca e fulfillments
payments:write Registrar pagamentos e criar checkouts Asaas
checkout_intents:read Consultar intenções de pré-checkout sem dados pessoais
checkout_intents:write Iniciar e concluir intenções de pré-checkout
commissions:read Consultar lancamentos de comissao
* Acesso total aos escopos da API publica

A API publica comercial nao expoe exclusao de itens ou vendas. Tambem nao expoe configuracao do Asaas, planos de comissao ou alteracao direta de recebiveis.

5.1 Intenções de pré-checkout#

O fluxo recebe um token aleatório do sistema externo. A primeira chamada registra somente a intenção anônima: não cria contato ou oportunidade. Quando a mesma pessoa fornece seus dados, a conclusão atualiza ou cria o contato e abre uma oportunidade na etapa inicial do pipeline padrão ativo. O token deve ter entre 32 e 128 caracteres, ser aleatório e não deve ser enviado na URL. O servidor persiste apenas o hash SHA-256.

  • Requer usuário ativo associado ao token, como as demais operações comerciais.
  • A organização é determinada pelo bearer; organizationId, se enviado, só valida que corresponde à organização do token.
  • source identifica o sistema/origem. Reusar token com outra origem retorna conflito.
  • O telefone é obrigatório e é a chave primária de resolução exata do contato. Revisões da intenção não podem trocar a identidade.
  • revision começa em 1; chamadas idênticas são idempotentes. Revisão antiga ou mesmos números com conteúdo divergente retornam conflito.
  • tracking e urlParameters aceitam atributos de atribuição, incluindo UTM e click IDs. O servidor limita quantidade e tamanho.
  • Eventos internos pre_checkout.started, pre_checkout.completed e pre_checkout.converted podem disparar Flows. O endpoint não envia mensagens.
  • Webhooks Asaas consultam o customer pela integração salva e vinculam a intenção usando telefone normalizado exato. Correspondência ambígua ou conflito de identidade bloqueia o vínculo para evitar duplicidade.

5.1 Iniciar intenção anônima

  • Metodo: POST
  • Rota: /api/v1/public-api/commercial/pre-checkout-intents
  • Autenticacao: Bearer token
  • Escopo exigido: checkout_intents:write
JSON
{
  "token": "b6c295f0-f923-4d4e-841e-a2c0647d47ae",
  "source": "checkout-site-cliente",
  "occurredAt": "2026-10-16T12:30:00.000Z",
  "tracking": { "utm_source": "google", "utm_campaign": "campanha-exemplo" },
  "urlParameters": { "gclid": "click-id-exemplo" }
}

Retorna 201 na criação e 200 em repetição idempotente. Não contém dados pessoais.

5.2 Completar intenção com dados do contato

  • Metodo: POST
  • Rota: /api/v1/public-api/commercial/pre-checkout-intents/complete
  • Autenticacao: Bearer token
  • Escopo exigido: checkout_intents:write
JSON
{
  "token": "b6c295f0-f923-4d4e-841e-a2c0647d47ae",
  "source": "checkout-site-cliente",
  "revision": 1,
  "contact": {
    "name": "Pessoa Exemplo",
    "phoneNumber": "+5511999990000",
    "email": "[email protected]",
    "documentNumber": "12345678901"
  },
  "purchase": { "currency": "BRL", "expectedTotal": "97.00", "productReference": "curso-exemplo" },
  "tracking": { "utm_source": "google", "utm_campaign": "campanha-exemplo" },
  "urlParameters": { "gclid": "click-id-exemplo" }
}

O telefone precisa incluir código do país e DDD. O retorno inclui contactId e opportunityId; intenção repetida com os mesmos dados retorna 200 sem duplicar registros.

5.3 Consultar intenção

  • Metodo: GET
  • Rota: /api/v1/public-api/commercial/pre-checkout-intents/:intentId
  • Autenticacao: Bearer token
  • Escopo exigido: checkout_intents:read

Retorna id, state (started, completed, converted ou expired), origem, timestamps e IDs relacionados. Nunca retorna o token bruto nem dados pessoais.

  • Metodo: GET
  • Rota: /api/v1/public-api/catalog/items
  • Autenticacao: Bearer token
  • Escopo exigido: catalog:read

Parametros de query

Campo Tipo Obrigatorio Descricao
search string Nao Ate 160 caracteres. Busca por nome, codigo, descricao curta, SKU ou marca
type string Nao product, service, plan_subscription, real_estate, vehicle_machine_equipment, education, event_ticket ou fee_additional
status string Nao draft, active ou inactive
templateId UUID Nao Filtra pelo template do item
categoryId UUID Nao Filtra por categoria
commercialMode string Nao sale, service, subscription, rental, daily, reservation, enrollment, licensing, additional_charge, quote, consultation, free ou internal
billingMode string Nao one_time, installment ou recurring
attributeFilters objeto JSON Nao Pode ser enviado como JSON serializado na query
tag string Nao Ate 160 caracteres
unitId UUID Nao Filtra pela unidade cadastrada
includeArchived boolean Nao true inclui arquivados
page inteiro Nao Minimo 1; padrao 1
limit inteiro Nao Entre 1 e 100; padrao 20

Exemplo de requisicao

BASH
curl --request GET \
  --url "https://api.wizer.digital/api/v1/public-api/catalog/items?status=active&type=service&page=1&limit=20" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO"

Exemplo de resposta

JSON
{
  "items": [
    {
      "id": "a43a6710-3b99-4c5d-b417-f4c4893c4c91",
      "templateId": "2adf5512-4dc1-4f96-bfa8-4c6e0a68730d",
      "type": "service",
      "name": "Consultoria estrategica",
      "code": "CONSULTORIA-ESTRATEGICA",
      "status": "active",
      "unit": "hora",
      "brand": "Wizer",
      "tags": ["consultoria"],
      "visibility": "organization",
      "compositionType": "simple",
      "offers": [],
      "categoryLinks": [],
      "attributeValues": [],
      "components": [],
      "media": [],
      "createdAt": "2026-07-22T12:00:00.000Z",
      "updatedAt": "2026-07-22T12:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
  • Metodo: GET
  • Rota: /api/v1/public-api/catalog/items/:itemId
  • Autenticacao: Bearer token
  • Escopo exigido: catalog:read

Parametros de path

Campo Tipo Obrigatorio Descricao
itemId UUID Sim ID do item na organizacao do token

Retorna o item com suas ofertas, categorias, atributos, componentes e midias, quando existentes. Itens arquivados nao sao retornados por esta rota publica.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/catalog/items/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "type": "product",
  "name": "Exemplo",
  "status": "draft"
}
  • Metodo: POST
  • Rota: /api/v1/public-api/catalog/items
  • Autenticacao: Bearer token
  • Escopo exigido: catalog:write

Parametros de body

Campo Tipo Obrigatorio Descricao
templateId UUID Sim Template comercial existente
name string Sim Ate 160 caracteres
code string Nao Ate 120 caracteres; letras, numeros, ponto, hifen e sublinhado
shortDescription string ou null Nao Ate 500 caracteres
description string ou null Nao Ate 10.000 caracteres
status string Nao draft, active ou inactive
primaryImage string ou null Nao Ate 2.000 caracteres
unit string ou null Nao Ate 40 caracteres
finalCost numero ou null Nao Maior ou igual a zero, ate 4 casas decimais
unitId UUID ou null Nao Unidade cadastrada
sku string ou null Nao Ate 120 caracteres
brand string ou null Nao Ate 160 caracteres
tags string[] Nao Valores unicos
ownerUserId UUID ou null Nao Usuario responsavel
visibility string Nao organization, public ou restricted
metadata objeto ou null Nao Metadados livres
compositionType string Nao simple ou composite
categoryIds UUID[] Nao IDs unicos de categorias
attributes objeto Nao Valores dos atributos definidos no template

Exemplo de requisicao

BASH
curl --request POST \
  --url "https://api.wizer.digital/api/v1/public-api/catalog/items" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  --header "Content-Type: application/json" \
  --data '{
    "templateId": "2adf5512-4dc1-4f96-bfa8-4c6e0a68730d",
    "name": "Consultoria estrategica",
    "code": "CONSULTORIA-ESTRATEGICA",
    "status": "active",
    "unit": "hora",
    "tags": ["consultoria"],
    "visibility": "organization",
    "compositionType": "simple",
    "attributes": {}
  }'

Exemplo de resposta

JSON
{
  "type": "product",
  "name": "Exemplo",
  "status": "draft"
}
  • Metodo: PATCH
  • Rota: /api/v1/public-api/catalog/items/:itemId
  • Autenticacao: Bearer token
  • Escopo exigido: catalog:write

Parametros de path

Campo Tipo Obrigatorio Descricao
itemId string Sim ID do item.

Parametros de body

Campo Tipo Obrigatorio Descricao
templateId UUID Nao Campo templateId.
name string Nao Campo name. Maximo de caracteres 160
code string Nao Campo code. Maximo de caracteres 120
shortDescription string ou null Nao Campo shortDescription. Maximo de caracteres 500
description string ou null Nao Campo description. Maximo de caracteres 10000
status draft | active | inactive Nao Campo status.
primaryImage string ou null Nao Campo primaryImage. Maximo de caracteres 2000
unit string ou null Nao Campo unit. Maximo de caracteres 40
finalCost number ou null Nao Campo finalCost. Minimo 0
unitId UUID ou null Nao Campo unitId.
sku string ou null Nao Campo sku. Maximo de caracteres 120
brand string ou null Nao Campo brand. Maximo de caracteres 160
tags string[] Nao Campo tags.
ownerUserId UUID ou null Nao Campo ownerUserId.
visibility organization | public | restricted Nao Campo visibility.
metadata object ou null Nao Campo metadata.
compositionType simple | composite Nao Campo compositionType.
categoryIds UUID[] Nao Campo categoryIds.
attributes object Nao Campo attributes.

Todos os campos de criacao sao opcionais no PATCH. O retorno e o item atualizado com as relacoes comerciais carregadas.

Exemplo de requisicao

BASH
curl -X PATCH "https://api.wizer.digital/api/v1/public-api/catalog/items/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "templateId": "11111111-1111-4111-8111-111111111111",
  "name": "Exemplo",
  "status": "draft"
}'

Exemplo de resposta

JSON
{
  "type": "product",
  "name": "Exemplo",
  "status": "draft"
}

5.5 Listar vendas#

  • Metodo: GET
  • Rota: /api/v1/public-api/sales
  • Autenticacao: Bearer token
  • Escopo exigido: sales:read

Parametros de query

Campo Tipo Obrigatorio Descricao
search string Nao Ate 160 caracteres
commercialStatus string Nao draft, awaiting_confirmation, confirmed, canceled ou completed
financialStatus string Nao not_applicable, not_charged, awaiting_payment, awaiting_settlement, partially_paid, paid, overdue, partially_refunded, refunded, disputed ou canceled
fulfillmentStatus string Nao not_applicable, pending, scheduled, preparing, in_progress, partially_completed, completed, suspended ou canceled
ownerUserId UUID Nao Responsavel pela venda
teamId UUID Nao Time da venda
opportunityId UUID Nao Oportunidade vinculada
contactId UUID Nao Contato da venda
createdFrom data ISO Nao Inicio do periodo de criacao
createdTo data ISO Nao Fim do periodo de criacao
page inteiro Nao Minimo 1; padrao 1
limit inteiro Nao Entre 1 e 100; padrao 20

Exemplo de resposta

JSON
{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "totalPages": 0
  }
}

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/sales?search=exemplo&commercialStatus=draft" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

5.6 Criar venda#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales
  • Autenticacao: Bearer token
  • Escopo exigido: sales:write

Parametros de body

Campo Tipo Obrigatorio Descricao
contactId UUID Sim Contato existente na organizacao
title string Nao De 1 a 160 caracteres
ownerUserId UUID ou null Nao Responsavel pela venda
teamId UUID ou null Nao Time responsavel
source string Nao dashboard, opportunity, chat_manual, ai_agent, flow, api, form, import ou integration; padrao publico api
currency string Nao Codigo de moeda com 3 caracteres
items objeto[] Sim Pelo menos um item
fulfillmentStatus string Nao Um status operacional valido
confirm boolean Nao Confirma a venda durante a criacao
idempotencyKey string Nao De 1 a 120 caracteres
notes string ou null Nao Ate 5.000 caracteres
metadata objeto ou null Nao Metadados livres

Campos de items

Campo Tipo Obrigatorio Descricao
catalogItemId UUID Sim Item do catalogo
catalogOfferId UUID Sim Oferta pertencente ao item
isPrimary boolean Nao Indica o item principal
position inteiro ou null Nao Maior ou igual a zero
quantity numero Nao Maior ou igual a 0.0001; padrao definido pelo servico
unitPrice numero ou null Nao Maior ou igual a zero
cost numero ou null Nao Maior ou igual a zero
setupFee numero ou null Nao Maior ou igual a zero
recurringAmount numero ou null Nao Maior ou igual a zero
discountType string Nao none, percentage ou fixed
discountValue numero Nao Maior ou igual a zero
additionalValue numero Nao Maior ou igual a zero
selectedAttributes objeto ou null Nao Atributos escolhidos
metadata objeto ou null Nao Metadados do item da venda

Exemplo de requisicao

BASH
curl --request POST \
  --url "https://api.wizer.digital/api/v1/public-api/sales" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  --header "Content-Type: application/json" \
  --data '{
    "contactId": "d25074cc-930f-45d2-a95a-dd6ef926535f",
    "title": "Contrato Consultoria",
    "currency": "BRL",
    "items": [
      {
        "catalogItemId": "a43a6710-3b99-4c5d-b417-f4c4893c4c91",
        "catalogOfferId": "dc416fba-83ea-4f05-bb80-442ba942ea2d",
        "isPrimary": true,
        "quantity": 1,
        "unitPrice": 1500,
        "discountType": "none",
        "discountValue": 0
      }
    ],
    "confirm": false,
    "idempotencyKey": "erp-order-123"
  }'

Exemplo de resposta

JSON
{}

5.7 Consultar venda#

  • Metodo: GET
  • Rota: /api/v1/public-api/sales/:saleId
  • Autenticacao: Bearer token
  • Escopo exigido: sales:read

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Retorna a venda completa, incluindo contato resumido, oportunidade, responsavel, time, itens, historico de status e os totais subtotal, discountTotal, additionalTotal, initialAmount, recurringAmount, expectedTotal, paidTotal e outstandingTotal.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{}

5.8 Atualizar venda#

  • Metodo: PATCH
  • Rota: /api/v1/public-api/sales/:saleId
  • Autenticacao: Bearer token
  • Escopo exigido: sales:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Parametros de body

Campo Tipo Obrigatorio Descricao
title string Nao Campo title. Minimo de caracteres 1; Maximo de caracteres 160
contactId UUID Nao Campo contactId.
ownerUserId UUID ou null Nao Campo ownerUserId.
teamId UUID ou null Nao Campo teamId.
notes string ou null Nao Campo notes. Maximo de caracteres 5000
metadata object ou null Nao Campo metadata.
items object[] Nao Campo items.

O body aceita title, contactId, ownerUserId, teamId, notes, metadata e uma nova lista completa de items. Os campos de status nao sao atualizados diretamente por este endpoint.

Exemplo de requisicao

BASH
curl -X PATCH "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "participantIds": ["22222222-2222-4222-8222-222222222222"]
}'

Exemplo de resposta

JSON
{}

5.9 Cancelar venda#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales/:saleId/cancel
  • Autenticacao: Bearer token
  • Escopo exigido: sales:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Parametros de body

Campo Tipo Obrigatorio Descricao
reason string Sim Campo reason. Minimo de caracteres 3; Maximo de caracteres 1000
JSON
{
  "reason": "Cliente desistiu da compra"
}

reason e obrigatorio e deve ter entre 3 e 1.000 caracteres.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/cancel" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "reason": "texto de exemplo"
}'

Exemplo de resposta

JSON
{}

5.10 Concluir venda#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales/:saleId/complete
  • Autenticacao: Bearer token
  • Escopo exigido: sales:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Conclui comercialmente uma venda confirmada, respeitando as transicoes de status permitidas pelo modulo.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/complete" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{}

5.11 Confirmar venda#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales/:saleId/confirm
  • Autenticacao: Bearer token
  • Escopo exigido: sales:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Confirma uma venda em draft ou awaiting_confirmation. Uma venda cancelada ou concluida nao pode retornar a estados anteriores.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/confirm" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{}

5.12 Consultar operacoes da venda#

  • Metodo: GET
  • Rota: /api/v1/public-api/sales/:saleId/operations
  • Autenticacao: Bearer token
  • Escopo exigido: sales:read

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Retorna o resumo operacional e financeiro da venda, incluindo saleId, currency, financialStatus, fulfillmentStatus, totais, recebiveis, chargeGroups, payments e fulfillments.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/operations" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{}

5.13 Criar grupo de cobranca#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales/:saleId/charge-groups
  • Autenticacao: Bearer token
  • Escopo exigido: sales:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Parametros de body

Campo Tipo Obrigatorio Descricao
name string Sim De 1 a 160 caracteres
billingMode string Sim one_time, installment ou recurring
amount numero Sim Maior ou igual a 0.0001
currency string Nao Codigo com 3 caracteres
dueDate data ISO ou null Nao Vencimento
installmentCount inteiro ou null Condicional Minimo 2 para parcelamento
billingInterval string ou null Condicional Ate 24 caracteres para recorrencia
billingIntervalCount inteiro ou null Nao Minimo 1
recurrenceEndDate data ISO ou null Nao Fim da recorrencia
saleItemIds UUID[] Nao Itens unicos alocados ao grupo
provider string ou null Nao Ate 40 caracteres
externalReference string ou null Nao Ate 180 caracteres
notes string ou null Nao Ate 2.000 caracteres
metadata objeto ou null Nao Metadados livres

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/charge-groups" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Exemplo",
  "billingMode": "one_time",
  "amount": 0.0001
}'

Exemplo de resposta

JSON
{}

5.14 Criar fulfillment#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales/:saleId/fulfillments
  • Autenticacao: Bearer token
  • Escopo exigido: sales:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Parametros de body

Campo Tipo Obrigatorio Descricao
saleItemId UUID ou null Nao Item especifico da venda
type string Sim product_delivery, digital_delivery, service, appointment, rental, reservation, event, enrollment ou other
status string Nao Status operacional valido
releasePolicy string Nao manual, on_first_payment ou on_full_payment
responsibleUserId UUID ou null Nao Responsavel pela execucao
scheduledStart data ISO ou null Nao Inicio agendado
scheduledEnd data ISO ou null Nao Fim agendado
completedAt data ISO ou null Nao Data de conclusao
location string ou null Nao Ate 255 caracteres
quantity numero ou null Nao Maior ou igual a 0.0001
notes string ou null Nao Ate 5.000 caracteres
metadata objeto ou null Nao Metadados livres

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/fulfillments" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "type": "product_delivery",
  "status": "not_applicable"
}'

Exemplo de resposta

JSON
{}

5.15 Listar checkouts da venda#

  • Metodo: GET
  • Rota: /api/v1/public-api/sales/:saleId/checkouts
  • Autenticacao: Bearer token
  • Escopo exigido: sales:read

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Retorna os checkouts da venda com identificadores, grupo de cobranca, provedor, status, URL, tipo de cobranca, meios aceitos, valor, moeda, expiracao, recebiveis e assinatura quando aplicavel.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/checkouts" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
[
  {}
]

5.16 Criar checkout Asaas#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales/:saleId/checkouts
  • Autenticacao: Bearer token
  • Escopo exigido: payments:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Parametros de body

Campo Tipo Obrigatorio Descricao
chargeGroupId string Sim Grupo de cobranca da venda
receivableId UUID Nao Recebivel avulso ou primeiro ciclo recorrente
receivableIds UUID[] Nao Entre 1 e 21 recebiveis para checkout parcelado
billingTypes string[] Sim Entre 1 e 2 valores: PIX e/ou CREDIT_CARD
minutesToExpire inteiro Nao Entre 10 e 1440; padrao 120
maxInstallmentCount inteiro Nao Entre 2 e 21
replaceActiveCheckout boolean Nao Padrao false
successUrl string Nao Ate 500 caracteres
cancelUrl string Nao Ate 500 caracteres
expiredUrl string Nao Ate 500 caracteres

O checkout exige conexao Asaas configurada, venda elegivel e compatibilidade entre o grupo de cobranca, os recebiveis e o tipo de cobranca.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/checkouts" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "chargeGroupId": "11111111-1111-4111-8111-111111111111",
  "billingTypes": [
    "PIX"
  ]
}'

Exemplo de resposta

JSON
{}

5.17 Registrar pagamento#

  • Metodo: POST
  • Rota: /api/v1/public-api/sales/:saleId/payments
  • Autenticacao: Bearer token
  • Escopo exigido: payments:write

Parametros de path

Campo Tipo Obrigatorio Descricao
saleId string Sim ID da venda.

Parametros de body

Campo Tipo Obrigatorio Descricao
chargeGroupId UUID ou null Nao Grupo de cobranca relacionado
method string Sim pix, bank_transfer, cash, credit_card, debit_card, external_boleto, trade, complimentary, compensation ou other
status string Nao pending, confirmed, received, canceled ou refunded
source string Nao manual, external ou integration; na API publica o padrao e external
amount numero Sim Maior ou igual a 0.0001
currency string Nao Codigo com 3 caracteres
paidAt data ISO ou null Nao Data do pagamento
dueDate data ISO ou null Nao Data de vencimento
externalReference string ou null Nao Ate 180 caracteres
proofUrl string ou null Nao Ate 2.000 caracteres
notes string ou null Nao Ate 2.000 caracteres
metadata objeto ou null Nao Metadados livres

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/sales/11111111-1111-4111-8111-111111111111/payments" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "method": "pix",
  "amount": 0.0001,
  "status": "pending"
}'

Exemplo de resposta

JSON
{}

5.18 Listar lancamentos de comissao#

  • Metodo: GET
  • Rota: /api/v1/public-api/commissions
  • Autenticacao: Bearer token
  • Escopo exigido: commissions:read

Parametros de query

Campo Tipo Obrigatorio Descricao
status string Nao projected, pending_eligibility, earned, pending_approval, approved, scheduled, paid, suspended, reversed ou canceled
participantUserId UUID Nao Agentes permanecem limitados aos proprios lancamentos
competenceFrom data ISO Nao Inicio da competencia
competenceTo data ISO Nao Fim da competencia
page inteiro Nao Minimo 1; padrao 1
limit inteiro Nao Entre 1 e 100; padrao 25

A resposta segue { "data": [...], "meta": {...}, "summary": {...} }. O acesso aos lancamentos de outros usuarios depende do papel e das permissoes do usuario associado ao token.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/commissions?status=projected&participantUserId=11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{}

6) Modulo financeiro#

A API publica do modulo financeiro expoe 6 operacoes para consultar categorias, listar e consultar lancamentos, criar despesas ou receitas, atualizar lancamentos manuais e registrar baixas.

Todas as rotas usam Authorization: Bearer <public-api-token>. Operacoes de escrita exigem que o token esteja associado a um usuario ativo da organizacao. Os dados sempre ficam limitados a organizacao vinculada ao token.

Escopos financeiros#

Escopo Operacoes permitidas
financial:read Listar categorias e consultar lancamentos financeiros
financial:write Criar e atualizar lancamentos manuais e registrar baixas
* Acesso total aos escopos da API publica

Lancamentos sincronizados de outros modulos, como recebiveis comerciais, podem ser consultados e baixados, mas nao podem ser alterados diretamente. Para corrigir seus dados, altere o registro no modulo de origem.

6.1 Listar categorias financeiras#

  • Metodo: GET
  • Rota: /api/v1/public-api/financial/categories
  • Autenticacao: Bearer token
  • Escopo exigido: financial:read

Retorna apenas categorias ativas da organizacao, ordenadas por direcao, ordem configurada e nome.

Exemplo de requisicao

BASH
curl --request GET \
  --url "https://api.wizer.digital/api/v1/public-api/financial/categories" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO"

Exemplo de resposta

JSON
[
  {
    "id": "62ec8909-9087-4c35-9bc0-d26a32729de1",
    "direction": "expense",
    "name": "Marketing",
    "parentId": null,
    "isSystem": false,
    "isActive": true,
    "sortOrder": 10,
    "createdAt": "2026-07-23T12:00:00.000Z",
    "updatedAt": "2026-07-23T12:00:00.000Z"
  }
]

6.2 Listar lancamentos financeiros#

  • Metodo: GET
  • Rota: /api/v1/public-api/financial/entries
  • Autenticacao: Bearer token
  • Escopo exigido: financial:read

Antes da listagem, o sistema sincroniza os recebiveis do modulo comercial. A resposta e um array ordenado por vencimento e data de criacao.

Parametros de query

Campo Tipo Obrigatorio Descricao
direction string Nao income para receita ou expense para despesa
status string Nao draft, pending, partially_settled, settled, overdue ou canceled
startDate data YYYY-MM-DD Nao Vencimento inicial, inclusive
endDate data YYYY-MM-DD Nao Vencimento final, inclusive
search string Nao Ate 160 caracteres. Busca na descricao ou contraparte

Exemplo de requisicao

BASH
curl --request GET \
  --url "https://api.wizer.digital/api/v1/public-api/financial/entries?direction=expense&status=pending&startDate=2026-08-01&endDate=2026-08-31" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO"

Exemplo de resposta

JSON
[
  {
    "id": "dd0fc244-02db-433d-9e99-26d04432db42",
    "direction": "expense",
    "status": "pending",
    "description": "Servico de contabilidade",
    "categoryId": "62ec8909-9087-4c35-9bc0-d26a32729de1",
    "counterpartyName": "Contabilidade Exemplo",
    "competenceDate": "2026-08-01",
    "dueDate": "2026-08-10",
    "currency": "BRL",
    "grossAmount": "850.0000",
    "netAmount": "850.0000",
    "settledAmount": "0.0000",
    "outstandingAmount": "850.0000",
    "sourceModule": "manual",
    "createdAt": "2026-07-23T12:00:00.000Z",
    "updatedAt": "2026-07-23T12:00:00.000Z"
  }
]

6.3 Consultar lancamento financeiro#

  • Metodo: GET
  • Rota: /api/v1/public-api/financial/entries/:entryId
  • Autenticacao: Bearer token
  • Escopo exigido: financial:read

Parametros de path

Campo Tipo Obrigatorio Descricao
entryId UUID Sim ID do lancamento financeiro

Exemplo de requisicao

BASH
curl --request GET \
  --url "https://api.wizer.digital/api/v1/public-api/financial/entries/dd0fc244-02db-433d-9e99-26d04432db42" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO"

A resposta contem o objeto completo do lancamento financeiro.

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "direction": "income",
  "status": "draft",
  "description": "Descricao de exemplo",
  "competenceDate": "2026-10-07",
  "dueDate": "2026-10-07",
  "currency": "BRL",
  "grossAmount": "texto de exemplo"
}

6.4 Criar lancamento financeiro#

  • Metodo: POST
  • Rota: /api/v1/public-api/financial/entries
  • Autenticacao: Bearer token
  • Escopo exigido: financial:write

O endpoint retorna um array porque uma unica requisicao pode gerar varias parcelas.

Parametros de body

Campo Tipo Obrigatorio Descricao
direction string Sim income ou expense
description string Sim Descricao do lancamento
categoryId UUID Nao Categoria financeira da mesma organizacao
counterpartyName string Nao Cliente, fornecedor ou outra contraparte
competenceDate data YYYY-MM-DD Sim Data de competencia
dueDate data YYYY-MM-DD Sim Primeiro vencimento
grossAmount number Sim Valor bruto, maior ou igual a zero
discountAmount number Nao Desconto. Padrao 0
interestAmount number Nao Juros. Padrao 0
fineAmount number Nao Multa. Padrao 0
feeAmount number Nao Taxas. Padrao 0
notes string Nao Observacoes
status string Nao draft, pending ou settled
installmentCount inteiro Nao Entre 1 e 120; gera parcelas mensais
recurring boolean Nao Cria uma configuracao recorrente
frequency string Condicional Obrigatorio quando recurring=true: weekly, monthly, bimonthly, quarterly, semiannual ou annual
recurrenceEndDate data YYYY-MM-DD Nao Termino da recorrencia
attachmentFileIds UUID[] Nao IDs de arquivos ja enviados ao CRM
extractionId UUID Nao ID de extracao documental existente

Exemplo de requisicao

BASH
curl --request POST \
  --url "https://api.wizer.digital/api/v1/public-api/financial/entries" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  --header "Content-Type: application/json" \
  --data '{
    "direction": "expense",
    "description": "Servico de contabilidade",
    "categoryId": "62ec8909-9087-4c35-9bc0-d26a32729de1",
    "counterpartyName": "Contabilidade Exemplo",
    "competenceDate": "2026-08-01",
    "dueDate": "2026-08-10",
    "grossAmount": 850,
    "status": "pending",
    "installmentCount": 1
  }'

Exemplo de resposta

JSON
[
  {
    "id": "dd0fc244-02db-433d-9e99-26d04432db42",
    "direction": "expense",
    "status": "pending",
    "description": "Servico de contabilidade",
    "grossAmount": "850",
    "netAmount": "850",
    "settledAmount": "0",
    "outstandingAmount": "850",
    "sourceModule": "manual"
  }
]

6.5 Atualizar lancamento financeiro manual#

  • Metodo: PATCH
  • Rota: /api/v1/public-api/financial/entries/:entryId
  • Autenticacao: Bearer token
  • Escopo exigido: financial:write

Parametros de path

Campo Tipo Obrigatorio Descricao
entryId string Sim ID do lancamento financeiro.

Parametros de body

Campo Tipo Obrigatorio Descricao
direction income | expense Nao Campo direction.
description string Nao Campo description.
categoryId UUID Nao Campo categoryId.
counterpartyName string Nao Campo counterpartyName.
competenceDate string (data) Nao Campo competenceDate.
dueDate string (data) Nao Campo dueDate.
grossAmount number Nao Campo grossAmount. Minimo 0
discountAmount number Nao Campo discountAmount. Minimo 0
interestAmount number Nao Campo interestAmount. Minimo 0
fineAmount number Nao Campo fineAmount. Minimo 0
feeAmount number Nao Campo feeAmount. Minimo 0
notes string Nao Campo notes.
status draft | pending | settled Nao Campo status.
installmentCount integer Nao Campo installmentCount. Minimo 1; Maximo 120
recurring boolean Nao Campo recurring.
frequency weekly | monthly | bimonthly | quarterly | semiannual | annual Nao Campo frequency.
recurrenceEndDate string (data) Nao Campo recurrenceEndDate.
attachmentFileIds UUID[] Nao Campo attachmentFileIds.
extractionId UUID Nao Campo extractionId.

Aceita os mesmos campos do endpoint de criacao, todos opcionais. Somente lancamentos com sourceModule="manual" podem ser atualizados diretamente.

Exemplo de requisicao

BASH
curl --request PATCH \
  --url "https://api.wizer.digital/api/v1/public-api/financial/entries/dd0fc244-02db-433d-9e99-26d04432db42" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  --header "Content-Type: application/json" \
  --data '{
    "description": "Contabilidade mensal - agosto",
    "dueDate": "2026-08-15",
    "notes": "Vencimento renegociado"
  }'

A resposta contem o lancamento atualizado.

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "direction": "income",
  "status": "draft",
  "description": "Descricao de exemplo",
  "competenceDate": "2026-10-07",
  "dueDate": "2026-10-07",
  "currency": "BRL",
  "grossAmount": "texto de exemplo"
}

6.6 Registrar baixa total ou parcial#

  • Metodo: POST
  • Rota: /api/v1/public-api/financial/entries/:entryId/settle
  • Autenticacao: Bearer token
  • Escopo exigido: financial:write

Parametros de path

Campo Tipo Obrigatorio Descricao
entryId string Sim ID do lancamento financeiro.

Parametros de body

Campo Tipo Obrigatorio Descricao
amount number Nao Valor positivo da baixa. Quando omitido, baixa todo o saldo pendente

Exemplo de baixa parcial

BASH
curl --request POST \
  --url "https://api.wizer.digital/api/v1/public-api/financial/entries/dd0fc244-02db-433d-9e99-26d04432db42/settle" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 400
  }'

Quando o valor acumulado for menor que o valor liquido, o status passa para partially_settled. Quando todo o saldo for baixado, passa para settled.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/financial/entries/11111111-1111-4111-8111-111111111111/settle" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "amount": 0.01
}'

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "direction": "income",
  "status": "draft",
  "description": "Descricao de exemplo",
  "competenceDate": "2026-10-07",
  "dueDate": "2026-10-07",
  "currency": "BRL",
  "grossAmount": "texto de exemplo"
}

Integrações e boas práticas#

8) Tarefas#

Todas as consultas e alteracoes ficam limitadas a organizacao do token. tasks:read da acesso a todas as tarefas dessa organizacao; tasks:write habilita as alteracoes descritas abaixo. Os status listados sao somente os ativos. O detalhe publico omite eventos internos e arquivos.

8.1 Listar status ativos de tarefas#

  • Metodo: GET
  • Rota: /api/v1/public-api/tasks/statuses
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:read

Retorna as colunas/status ativos da organizacao, ordenados pela posicao.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/tasks/statuses" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
[
  {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "A fazer",
    "color": "#FF7A1A",
    "position": 0,
    "isInitial": true,
    "isCompleted": false,
    "isActive": true,
    "isDefault": true
  }
]

8.2 Listar tarefas#

  • Metodo: GET
  • Rota: /api/v1/public-api/tasks
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:read

Parametros de query

Campo Tipo Obrigatorio Descricao
q string Nao Busca por titulo, descricao ou numero. Maximo de caracteres 200
statusId UUID Nao Status da tarefa.
participantId UUID Nao Usuario participante.
conversationId UUID Nao Conversa vinculada.
contactId UUID Nao Contato vinculado.
state open | completed | all Nao Estado combinado. Padrao open
limit integer Nao Itens por pagina. Padrao 30; Minimo 1; Maximo 100
offset integer Nao Deslocamento. Padrao 0; Minimo 0

A resposta contem data e meta com total, page, limit, offset e totalPages.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/tasks?q=exemplo&statusId=11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "number": "TASK-100",
      "title": "Retornar para Maria",
      "description": "Enviar a proposta comercial",
      "statusId": "33333333-3333-4333-8333-333333333333",
      "status": {
        "id": "33333333-3333-4333-8333-333333333333",
        "name": "A fazer",
        "color": "#FF7A1A",
        "position": 0,
        "isInitial": true,
        "isCompleted": false,
        "isActive": true,
        "isDefault": true
      },
      "contact": {
        "id": "44444444-4444-4444-8444-444444444444",
        "name": "Maria Souza",
        "email": "[email protected]",
        "phoneNumber": "5511999999999"
      },
      "participants": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "name": "Ana Lima",
          "email": "[email protected]",
          "addedAt": "2026-10-07T12:00:00.000Z"
        }
      ],
      "conversations": [],
      "source": "public_api",
      "completedAt": null,
      "lastActivityAt": "2026-10-07T12:00:00.000Z",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "updatedAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 30,
    "offset": 0,
    "totalPages": 1
  }
}

8.3 Consultar tarefa#

  • Metodo: GET
  • Rota: /api/v1/public-api/tasks/:taskId
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:read

Parametros de path

Campo Tipo Obrigatorio Descricao
taskId string Sim ID da tarefa.

Retorna dados da tarefa, status, contato, participantes, comentarios e conversas vinculadas. Eventos internos e arquivos nao sao expostos.

Exemplo de requisicao

BASH
curl -X GET "https://api.wizer.digital/api/v1/public-api/tasks/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "number": "TASK-100",
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "statusId": "33333333-3333-4333-8333-333333333333",
  "status": {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "A fazer",
    "color": "#FF7A1A",
    "position": 0,
    "isInitial": true,
    "isCompleted": false,
    "isActive": true,
    "isDefault": true
  },
  "contact": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Maria Souza",
    "email": "[email protected]",
    "phoneNumber": "5511999999999"
  },
  "participants": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Ana Lima",
      "email": "[email protected]",
      "addedAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "conversations": [],
  "source": "public_api",
  "completedAt": null,
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z",
  "comments": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "content": "Comentario de exemplo",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "author": null
    }
  ]
}

8.4 Criar tarefa#

  • Metodo: POST
  • Rota: /api/v1/public-api/tasks
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:write

Parametros de body

Campo Tipo Obrigatorio Descricao
title string Sim Campo title. Minimo de caracteres 2; Maximo de caracteres 180
description string Nao Campo description. Maximo de caracteres 10000
statusId UUID Nao Campo statusId.
contactId UUID Nao Campo contactId.
conversationId UUID Nao Campo conversationId.
participantIds UUID[] Nao Campo participantIds.

Campos aceitos: title (2 a 180 caracteres, obrigatorio), description (ate 10.000 caracteres), statusId, contactId, conversationId e participantIds (ate 50 usuarios ativos da organizacao). A tarefa e registrada com origem public_api.

Se o token estiver associado a um usuario, esse usuario sera incluido automaticamente como participante. Sem usuario associado, informe pelo menos um participantIds; nenhum usuario ficticio sera criado. Comentarios e eventos dessas chamadas ficam com autor de usuario nulo, e eventos guardam origem public_api.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/tasks" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "participantIds": ["22222222-2222-4222-8222-222222222222"]
}'

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "number": "TASK-100",
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "statusId": "33333333-3333-4333-8333-333333333333",
  "status": {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "A fazer",
    "color": "#FF7A1A",
    "position": 0,
    "isInitial": true,
    "isCompleted": false,
    "isActive": true,
    "isDefault": true
  },
  "contact": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Maria Souza",
    "email": "[email protected]",
    "phoneNumber": "5511999999999"
  },
  "participants": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Ana Lima",
      "email": "[email protected]",
      "addedAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "conversations": [],
  "source": "public_api",
  "completedAt": null,
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z",
  "comments": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "content": "Comentario de exemplo",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "author": null
    }
  ]
}

8.5 Atualizar tarefa#

  • Metodo: PATCH
  • Rota: /api/v1/public-api/tasks/:taskId
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:write

Parametros de path

Campo Tipo Obrigatorio Descricao
taskId string Sim ID da tarefa.

Parametros de body

Campo Tipo Obrigatorio Descricao
title string Nao Campo title. Minimo de caracteres 2; Maximo de caracteres 180
description string ou null Nao Campo description.
statusId UUID Nao Campo statusId.
contactId UUID ou null Nao Campo contactId.

Aceita title, description, statusId e contactId. Use contactId: null para desvincular o contato.

Exemplo de requisicao

BASH
curl -X PATCH "https://api.wizer.digital/api/v1/public-api/tasks/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "Tarefa de exemplo"
}'

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "number": "TASK-100",
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "statusId": "33333333-3333-4333-8333-333333333333",
  "status": {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "A fazer",
    "color": "#FF7A1A",
    "position": 0,
    "isInitial": true,
    "isCompleted": false,
    "isActive": true,
    "isDefault": true
  },
  "contact": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Maria Souza",
    "email": "[email protected]",
    "phoneNumber": "5511999999999"
  },
  "participants": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Ana Lima",
      "email": "[email protected]",
      "addedAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "conversations": [],
  "source": "public_api",
  "completedAt": null,
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z",
  "comments": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "content": "Comentario de exemplo",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "author": null
    }
  ]
}

8.6 Adicionar comentario#

  • Metodo: POST
  • Rota: /api/v1/public-api/tasks/:taskId/comments
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:write

Parametros de path

Campo Tipo Obrigatorio Descricao
taskId string Sim ID da tarefa.

Parametros de body

Campo Tipo Obrigatorio Descricao
content string Sim Campo content. Minimo de caracteres 1; Maximo de caracteres 10000

Se nao houver usuario associado ao token, o autor do comentario sera nulo.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/tasks/11111111-1111-4111-8111-111111111111/comments" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "content": "Comentario de exemplo"
}'

Exemplo de resposta

JSON
{
  "id": "55555555-5555-4555-8555-555555555555",
  "content": "Comentario de exemplo",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "author": null
}

8.7 Adicionar participante#

  • Metodo: POST
  • Rota: /api/v1/public-api/tasks/:taskId/participants
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:write

Parametros de path

Campo Tipo Obrigatorio Descricao
taskId string Sim ID da tarefa.

Parametros de body

Campo Tipo Obrigatorio Descricao
userId UUID Sim Campo userId.

O usuario deve estar ativo e pertencer a organizacao do token.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/tasks/11111111-1111-4111-8111-111111111111/participants" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "userId": "11111111-1111-4111-8111-111111111111"
}'

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "number": "TASK-100",
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "statusId": "33333333-3333-4333-8333-333333333333",
  "status": {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "A fazer",
    "color": "#FF7A1A",
    "position": 0,
    "isInitial": true,
    "isCompleted": false,
    "isActive": true,
    "isDefault": true
  },
  "contact": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Maria Souza",
    "email": "[email protected]",
    "phoneNumber": "5511999999999"
  },
  "participants": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Ana Lima",
      "email": "[email protected]",
      "addedAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "conversations": [],
  "source": "public_api",
  "completedAt": null,
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z",
  "comments": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "content": "Comentario de exemplo",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "author": null
    }
  ]
}

8.8 Remover participante#

  • Metodo: DELETE
  • Rota: /api/v1/public-api/tasks/:taskId/participants/:userId
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:write

Parametros de path

Campo Tipo Obrigatorio Descricao
taskId string Sim ID da tarefa.
userId string Sim ID do usuario participante.

Uma tarefa precisa manter ao menos um participante.

Exemplo de requisicao

BASH
curl -X DELETE "https://api.wizer.digital/api/v1/public-api/tasks/11111111-1111-4111-8111-111111111111/participants/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "number": "TASK-100",
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "statusId": "33333333-3333-4333-8333-333333333333",
  "status": {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "A fazer",
    "color": "#FF7A1A",
    "position": 0,
    "isInitial": true,
    "isCompleted": false,
    "isActive": true,
    "isDefault": true
  },
  "contact": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Maria Souza",
    "email": "[email protected]",
    "phoneNumber": "5511999999999"
  },
  "participants": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Ana Lima",
      "email": "[email protected]",
      "addedAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "conversations": [],
  "source": "public_api",
  "completedAt": null,
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z",
  "comments": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "content": "Comentario de exemplo",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "author": null
    }
  ]
}

8.9 Vincular conversa#

  • Metodo: POST
  • Rota: /api/v1/public-api/tasks/:taskId/conversations
  • Autenticacao: Bearer token
  • Escopo exigido: tasks:write

Parametros de path

Campo Tipo Obrigatorio Descricao
taskId string Sim ID da tarefa.

Parametros de body

Campo Tipo Obrigatorio Descricao
conversationId UUID Sim Campo conversationId.

A conversa deve pertencer a mesma organizacao e, se a tarefa ja tiver contato, ao mesmo contato.

Exemplo de requisicao

BASH
curl -X POST "https://api.wizer.digital/api/v1/public-api/tasks/11111111-1111-4111-8111-111111111111/conversations" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
  "conversationId": "11111111-1111-4111-8111-111111111111"
}'

Exemplo de resposta

JSON
{
  "id": "11111111-1111-4111-8111-111111111111",
  "number": "TASK-100",
  "title": "Retornar para Maria",
  "description": "Enviar a proposta comercial",
  "statusId": "33333333-3333-4333-8333-333333333333",
  "status": {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "A fazer",
    "color": "#FF7A1A",
    "position": 0,
    "isInitial": true,
    "isCompleted": false,
    "isActive": true,
    "isDefault": true
  },
  "contact": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Maria Souza",
    "email": "[email protected]",
    "phoneNumber": "5511999999999"
  },
  "participants": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Ana Lima",
      "email": "[email protected]",
      "addedAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "conversations": [],
  "source": "public_api",
  "completedAt": null,
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z",
  "comments": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "content": "Comentario de exemplo",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "author": null
    }
  ]
}

9) Conversas#

Os endpoints de conversas exigem o escopo conversations:read e operam somente na organizacao vinculada ao token. Tokens com acesso completo (*) tambem podem consultar conversas. Tokens com outros escopos, como tasks:read, nao recebem esse acesso automaticamente.

As respostas incluem apenas campos previstos no contrato público. Mensagens privadas e mensagens de sistema nao sao retornadas. A consulta de mensagens nao altera o contador de mensagens nao lidas. Anexos e links de mídia nao fazem parte desta versão.

9.1 Listar conversas#

  • Metodo: GET
  • Rota: /api/v1/public-api/conversations
  • Autenticacao: Bearer token
  • Escopo exigido: conversations:read

Parametros de query

Campo Tipo Obrigatorio Descricao
contactId string (UUID) Nao Filtra pelo contato
status waiting | in_progress | finished | archived Nao Filtra pelo status da conversa
channel whatsapp | instagram | messenger | widget | web_widget Nao Filtra pelo canal
limit number Nao Itens por pagina. Padrao 20, minimo 1, maximo 100
cursor string Nao Cursor opaco retornado em meta.nextCursor

A resposta contem data e meta com limit, hasMore e nextCursor.

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/conversations?contactId=11111111-1111-4111-8111-111111111111&status=in_progress&channel=whatsapp&limit=2" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "contactId": "11111111-1111-4111-8111-111111111111",
      "contactName": "Marina Oliveira",
      "channel": "whatsapp",
      "status": "in_progress",
      "assigneeId": "33333333-3333-4333-8333-333333333333",
      "teamId": "44444444-4444-4444-8444-444444444444",
      "lastMessageAt": "2026-10-06T18:42:15.000Z",
      "createdAt": "2026-10-06T14:10:00.000Z"
    }
  ],
  "meta": {
    "limit": 2,
    "hasMore": true,
    "nextCursor": "eyJhdCI6IjIwMjYtMTAtMDZUMTQ6MTA6MDAuMDAwWiIsImlkIjoiLi4uIn0"
  }
}

9.2 Consultar conversa#

  • Metodo: GET
  • Rota: /api/v1/public-api/conversations/:conversationId
  • Autenticacao: Bearer token
  • Escopo exigido: conversations:read

Parametros de path

Campo Tipo Obrigatorio Descricao
conversationId string (UUID) Sim ID da conversa

A conversa deve pertencer a organizacao do token. Caso contrario, a API retorna 404 Not Found.

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/conversations/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "id": "22222222-2222-4222-8222-222222222222",
  "contactId": "11111111-1111-4111-8111-111111111111",
  "contactName": "Marina Oliveira",
  "channel": "whatsapp",
  "status": "in_progress",
  "assigneeId": "33333333-3333-4333-8333-333333333333",
  "teamId": "44444444-4444-4444-8444-444444444444",
  "lastMessageAt": "2026-10-06T18:42:15.000Z",
  "createdAt": "2026-10-06T14:10:00.000Z",
  "updatedAt": "2026-10-06T18:42:15.000Z"
}

9.3 Listar mensagens da conversa#

  • Metodo: GET
  • Rota: /api/v1/public-api/conversations/:conversationId/messages
  • Autenticacao: Bearer token
  • Escopo exigido: conversations:read

Parametros de path

Campo Tipo Obrigatorio Descricao
conversationId string (UUID) Sim ID da conversa

Parametros de query

Campo Tipo Obrigatorio Descricao
limit number Nao Mensagens por pagina. Padrao 30, minimo 1, maximo 100
cursor string Nao Cursor opaco retornado em meta.nextCursor

As mensagens sao retornadas em ordem cronologica. Mensagens privadas e de sistema sao omitidas.

Exemplo de requisicao

BASH
curl -X GET "https://seu-dominio.com/api/v1/public-api/conversations/22222222-2222-4222-8222-222222222222/messages?limit=30" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Accept: application/json"

Exemplo de resposta

JSON
{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "content": "Ola, gostaria de saber o prazo de entrega.",
      "direction": "incoming",
      "senderType": "contact",
      "sentAt": "2026-10-06T18:40:02.000Z",
      "status": "delivered"
    },
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "content": "O prazo estimado e de tres dias uteis.",
      "direction": "outgoing",
      "senderType": "user",
      "sentAt": "2026-10-06T18:42:15.000Z",
      "status": "sent"
    }
  ],
  "meta": {
    "limit": 30,
    "hasMore": false,
    "nextCursor": null
  }
}

Quando usar o token#

Use o token public API em integracoes externas como:

  • n8n
  • ERP
  • scripts internos
  • plataformas de automacao

Boas praticas#

  • Guarde o token com seguranca.
  • Use um token diferente para cada integracao externa.
  • Revogue o token quando a integracao nao for mais confiavel.
  • Nao reutilize o mesmo token em ambientes diferentes sem necessidade.
  • Gere um requestId por operacao logica e reutilize o mesmo ID apenas em retries da mesma operacao.
  • Ao receber 409 em configuracoes de agente, releia a secao antes de tentar uma nova alteracao.
  • Prefira alterar somente a secao necessaria, sem reconstruir configuracoes de outros dominios.

Limites e validacoes importantes#

  • Maximo de 3 tokens ativos por organizacao.
  • Todo acesso e sempre limitado a organizacao do token.
  • Nos endpoints de contato e oportunidade, os registros relacionados precisam pertencer a mesma organizacao.