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
Tokens da integracao: /api/v1/integrations/public-api/tokens

Autenticacao#

Header obrigatorio#

Todas as rotas publicas exigem:

HTTP

Authorization: Bearer <public-api-token>

Rotas que usam sessao do dashboard#

As rotas de token do Hub de Integracoes usam autenticacao interna da aplicacao e exigem perfil org-admin ou admin.

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

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; em identities, connectionId e identifier tambem nao sao expostos

Resumo dos endpoints#

Metodo	Rota	Autenticacao	Descricao
`GET`	`/api/v1/integrations/public-api/tokens`	Dashboard	Lista tokens da organizacao
`POST`	`/api/v1/integrations/public-api/tokens`	Dashboard	Cria novo token
`PATCH`	`/api/v1/integrations/public-api/tokens/:id`	Dashboard	Renomeia token
`DELETE`	`/api/v1/integrations/public-api/tokens/:id`	Dashboard	Revoga token
`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
`POST`	`/api/v1/public-api/users`	Bearer	Cria usuario
`PATCH`	`/api/v1/public-api/users/:id`	Bearer	Atualiza usuario
`DELETE`	`/api/v1/public-api/users/:id`	Bearer	Exclui usuario
`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
`GET`	`/api/v1/public-api/commissions`	Bearer	Lista lançamentos de comissão

1) Tokens da integracao#

1.1 Listar tokens#

Metodo: GET
Rota: /api/v1/integrations/public-api/tokens
Autenticacao: dashboard interno

Parametros

Nao possui parametros de path, query ou body.

Exemplo de requisicao

BASH

curl -X GET "https://seu-dominio.com/api/v1/integrations/public-api/tokens" \
  -H "Accept: application/json" \
  -H "Cookie: sua-sessao-do-dashboard"

Resposta

Retorna uma lista de tokens com dados mascarados.

Campos principais de cada item:

Campo	Tipo	Descricao
`id`	string	ID do registro do token
`name`	string	Nome exibido no Hub de Integracoes
`description`	string \| null	Descricao opcional
`tokenPrefix`	string	Prefixo nao sensivel do token
`lastFour`	string	Ultimos 4 caracteres do token
`maskedToken`	string	Valor mascarado para exibicao
`status`	`active` \| `revoked`	Situacao do token
`createdByUserId`	string \| null	Usuario que criou o token
`revokedByUserId`	string \| null	Usuario que revogou o token
`revokedAt`	string \| null	Data/hora da revogacao em ISO
`lastUsedAt`	string \| null	Ultimo uso bem-sucedido
`createdAt`	string	Data/hora de criacao em ISO
`updatedAt`	string	Data/hora de atualizacao em ISO

Exemplo de resposta

JSON

[
  {
    "id": "7b7cf8d7-7a94-4d8e-9a38-0dc1d79e8f74",
    "name": "Token para integrar ao ERP",
    "description": "Integracao principal",
    "tokenPrefix": "a1b2c3d4",
    "lastFour": "k9X2",
    "maskedToken": "a1b2c3d4****k9X2",
    "status": "active",
    "createdByUserId": "0d7fe8a4-8a6a-4f15-a5ad-3f21f3a2c2b1",
    "revokedByUserId": null,
    "revokedAt": null,
    "lastUsedAt": "2026-06-17T12:30:00.000Z",
    "createdAt": "2026-06-17T12:00:00.000Z",
    "updatedAt": "2026-06-17T12:00:00.000Z"
  }
]

1.2 Criar token#

Metodo: POST
Rota: /api/v1/integrations/public-api/tokens
Autenticacao: dashboard interno

Parametros de body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Sim	Nome obrigatorio do token. Ex.: `Token da integracao com n8n`
`description`	string	Nao	Descricao opcional para ajudar a identificar a integracao

Regras adicionais:

name e salvo com trim
description e opcional e tambem sofre trim
a organizacao pode ter no maximo 3 tokens ativos
o valor completo do token e retornado somente nessa resposta

Exemplo de requisicao

BASH

curl -X POST "https://seu-dominio.com/api/v1/integrations/public-api/tokens" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: sua-sessao-do-dashboard" \
  -d '{
    "name": "Token da integracao com n8n",
    "description": "Token para sincronizar contatos com o n8n"
  }'

Exemplo de resposta

JSON

{
  "id": "7b7cf8d7-7a94-4d8e-9a38-0dc1d79e8f74",
  "name": "Token da integracao com n8n",
  "description": "Token para sincronizar contatos com o n8n",
  "tokenPrefix": "a1b2c3d4",
  "lastFour": "k9X2",
  "maskedToken": "a1b2c3d4****k9X2",
  "status": "active",
  "createdByUserId": "0d7fe8a4-8a6a-4f15-a5ad-3f21f3a2c2b1",
  "revokedByUserId": null,
  "revokedAt": null,
  "lastUsedAt": null,
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z",
  "token": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"
}

1.3 Renomear token#

Metodo: PATCH
Rota: /api/v1/integrations/public-api/tokens/:id
Autenticacao: dashboard interno

Parametros de path

Campo	Tipo	Obrigatorio	Descricao
`id`	string	Sim	ID do token que sera renomeado

Parametros de body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Nao	Novo nome do token
`description`	string	Nao	Nova descricao do token

Observacao:

se name vier vazio apos trim, a requisicao falha
o segredo do token nao muda

Exemplo de requisicao

BASH

curl -X PATCH "https://seu-dominio.com/api/v1/integrations/public-api/tokens/7b7cf8d7-7a94-4d8e-9a38-0dc1d79e8f74" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: sua-sessao-do-dashboard" \
  -d '{
    "name": "Token para ERP",
    "description": "Integracao com o ERP principal"
  }'

Exemplo de resposta

JSON

{
  "id": "7b7cf8d7-7a94-4d8e-9a38-0dc1d79e8f74",
  "name": "Token para ERP",
  "description": "Integracao com o ERP principal",
  "tokenPrefix": "a1b2c3d4",
  "lastFour": "k9X2",
  "maskedToken": "a1b2c3d4****k9X2",
  "status": "active",
  "createdByUserId": "0d7fe8a4-8a6a-4f15-a5ad-3f21f3a2c2b1",
  "revokedByUserId": null,
  "revokedAt": null,
  "lastUsedAt": null,
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:15:00.000Z"
}

1.4 Revogar token#

Metodo: DELETE
Rota: /api/v1/integrations/public-api/tokens/:id
Autenticacao: dashboard interno

Parametros de path

Campo	Tipo	Obrigatorio	Descricao
`id`	string	Sim	ID do token que sera revogado

Exemplo de requisicao

BASH

curl -X DELETE "https://seu-dominio.com/api/v1/integrations/public-api/tokens/7b7cf8d7-7a94-4d8e-9a38-0dc1d79e8f74" \
  -H "Accept: application/json" \
  -H "Cookie: sua-sessao-do-dashboard"

Exemplo de resposta

JSON

{
  "id": "7b7cf8d7-7a94-4d8e-9a38-0dc1d79e8f74",
  "name": "Token para ERP",
  "description": "Integracao com o ERP principal",
  "tokenPrefix": "a1b2c3d4",
  "lastFour": "k9X2",
  "maskedToken": "a1b2c3d4****k9X2",
  "status": "revoked",
  "createdByUserId": "0d7fe8a4-8a6a-4f15-a5ad-3f21f3a2c2b1",
  "revokedByUserId": "0d7fe8a4-8a6a-4f15-a5ad-3f21f3a2c2b1",
  "revokedAt": "2026-06-17T12:20:00.000Z",
  "lastUsedAt": null,
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:20:00.000Z"
}

2) 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.

2.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
  }
}

2.2 Consultar tag por id#

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

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

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

2.4 Atualizar tag#

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

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

2.5 Excluir tag#

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

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

Para excluir a tag e remover explicitamente todas as suas associacoes, use:

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"

Resposta:

JSON

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

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

2.6 Listar tags do contato#

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

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

2.7 Adicionar tag ao contato#

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

Body:

JSON

{
  "tagId": "8acc8a16-2256-4de1-85ed-33e56095e15f"
}

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.

2.8 Remover tag do contato#

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

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

2.9 Substituir todas as tags do contato#

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

Body:

JSON

{
  "tagIds": [
    "8acc8a16-2256-4de1-85ed-33e56095e15f",
    "c0416596-6bee-42dd-a14a-90989dad4957"
  ]
}

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: [].

3) Contatos#

3.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 de contato. Aceita array ou string separada por virgula
`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.

3.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"
}

3.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"
}

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

Parametros de body

Os mesmos campos do POST /contacts, todos opcionais:

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"
}

3.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
}

4) Oportunidades#

4.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
  }
}

4.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"
}

4.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"
}

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

Parametros de body

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

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"
}

4.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
}

5) Usuarios#

5.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
  }
}

5.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.3 Criar usuario#

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

Observacao importante:

o endpoint sempre cria o usuario na organizacao do token

Parametros de body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Sim	Nome completo do usuario
`email`	string	Sim	E-mail do usuario
`password`	string	Sim	Senha inicial
`role`	`user` \| `admin` \| `org-admin` \| `org-manager` \| `org-agent`	Nao	Papel do usuario
`roleMaskId`	string	Nao	ID do role mask da organizacao
`emailVerified`	boolean	Nao	Marca o e-mail como verificado
`isActive`	boolean	Nao	Define se o usuario ja entra ativo
`teamIds`	string[]	Nao	IDs dos times em que o usuario participa
`managedTeamIds`	string[]	Nao	IDs dos times gerenciados pelo usuario
`whatsapp`	string	Nao	WhatsApp com DDD, formatado e normalizado pelo backend

Exemplo de requisicao

BASH

curl -X POST "https://seu-dominio.com/api/v1/public-api/users" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Ana Silva",
    "email": "[email protected]",
    "password": "Senha123",
    "role": "org-agent",
    "isActive": true,
    "whatsapp": "(11) 99999-9999",
    "teamIds": [
      "11111111-1111-1111-1111-111111111111"
    ]
  }'

Exemplo de resposta

JSON

{
  "id": "user-1",
  "name": "Ana Silva",
  "email": "[email protected]",
  "bio": null,
  "profileLinks": [],
  "whatsapp": "11999999999",
  "avatarKey": null,
  "avatarUrl": null,
  "role": "org-agent",
  "roleDisplayName": "Org Agent",
  "roleMaskId": null,
  "isActive": true,
  "emailVerified": false,
  "authProvider": "local",
  "teams": [],
  "managedTeams": [],
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z"
}

5.4 Atualizar usuario#

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

Parametros de path

Campo	Tipo	Obrigatorio	Descricao
`id`	string	Sim	ID do usuario

Parametros de body

Os seguintes campos de criacao podem ser enviados neste endpoint: name, email, password, role, roleMaskId, isActive, teamIds, managedTeamIds e whatsapp. Todos sao opcionais no PATCH. Alem deles, o endpoint aceita:

Campo	Tipo	Obrigatorio	Descricao
`bio`	string	Nao	Biografia em HTML
`avatarKey`	string	Nao	Chave do avatar no storage
`profileLinks`	array	Nao	Lista de links publicos do perfil
`chatSettings`	object	Nao	Configuracoes de chat do usuario

O campo emailVerified, aceito na criacao, nao faz parte dos campos de atualizacao.

profileLinks

Cada item:

Campo	Tipo	Obrigatorio	Descricao
`label`	string	Sim	Rotulo do link
`url`	string	Sim	URL do link

chatSettings

Campo	Tipo	Obrigatorio	Descricao
`chatNotificationsSound`	boolean	Nao	Toca som em novas mensagens

Exemplo de requisicao

BASH

curl -X PATCH "https://seu-dominio.com/api/v1/public-api/users/user-1" \
  -H "Authorization: Bearer SEU_TOKEN_PUBLICO" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Ana Silva Martins",
    "bio": "<p>Equipe comercial</p>",
    "profileLinks": [
      {
        "label": "LinkedIn",
        "url": "https://linkedin.com/in/ana"
      }
    ],
    "chatSettings": {
      "chatNotificationsSound": true
    }
  }'

Exemplo de resposta

JSON

{
  "id": "user-1",
  "name": "Ana Silva Martins",
  "email": "[email protected]",
  "bio": "<p>Equipe comercial</p>",
  "profileLinks": [
    {
      "label": "LinkedIn",
      "url": "https://linkedin.com/in/ana"
    }
  ],
  "whatsapp": "11999999999",
  "avatarKey": null,
  "avatarUrl": null,
  "role": "org-agent",
  "roleDisplayName": "Org Agent",
  "roleMaskId": null,
  "isActive": true,
  "emailVerified": false,
  "authProvider": "local",
  "teams": [],
  "managedTeams": [],
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:10:00.000Z"
}

5.5 Excluir usuario#

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

Parametros de path

Campo	Tipo	Obrigatorio	Descricao
`id`	string	Sim	ID do usuario

Regras adicionais:

a exclusao e bloqueada se o usuario for o ultimo admin ativo da organizacao

Exemplo de requisicao

BASH

curl -X DELETE "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

{
  "success": true
}

6) 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
`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.

6.1 Listar itens do catalogo#

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

Parametros de query

Campo	Tipo	Obrigatorio	Regras
`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"

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
}

6.2 Consultar item do catalogo#

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.

6.3 Criar item do catalogo#

Metodo: POST
Rota: /api/v1/public-api/catalog/items
Autenticacao: Bearer token
Escopo exigido: catalog:write

Parametros de body

Campo	Tipo	Obrigatorio	Regras
`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": {}
  }'

6.4 Atualizar item do catalogo#

Metodo: PATCH
Rota: /api/v1/public-api/catalog/items/:itemId
Autenticacao: Bearer token
Escopo exigido: catalog:write

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

6.5 Listar vendas#

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

Parametros de query

Campo	Tipo	Obrigatorio	Regras
`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`

Resposta

JSON

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

6.6 Criar venda#

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

Parametros de body

Campo	Tipo	Obrigatorio	Regras
`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	Regras
`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"
  }'

6.7 Consultar venda#

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

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.

6.8 Atualizar venda#

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

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.

6.9 Cancelar venda#

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

JSON

{
  "reason": "Cliente desistiu da compra"
}

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

6.10 Concluir venda#

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

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

6.11 Confirmar venda#

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

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

6.12 Consultar operacoes da venda#

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

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

6.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 body

Campo	Tipo	Obrigatorio	Regras
`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

6.14 Criar fulfillment#

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

Parametros de body

Campo	Tipo	Obrigatorio	Regras
`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

6.15 Listar checkouts da venda#

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

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.

6.16 Criar checkout Asaas#

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

Parametros de body

Campo	Tipo	Obrigatorio	Regras
`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.

6.17 Registrar pagamento#

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

Parametros de body

Campo	Tipo	Obrigatorio	Regras
`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

6.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	Regras
`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.

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.

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.