> For the complete documentation index, see [llms.txt](https://ajuda.zdg.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.zdg.com.br/central-do-assinante/referencia-da-api/contatos.md). # 👤 Contatos ## POST /v2/api/external/{apiId}/blockContact > BlockContact ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/blockContact":{"post":{"tags":["👤 Contatos"],"summary":"BlockContact","operationId":"BlockContact","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"integer","description":"ID do contato que será bloqueado/desbloqueado"},"blocked":{"type":"boolean","description":"true para bloquear, false para desbloquear"}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/createContact > CreateContact ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/createContact":{"post":{"tags":["👤 Contatos"],"summary":"CreateContact","operationId":"CreateContact","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome completo do contato"},"number":{"type":"string","description":"Número do WhatsApp (formato: 5511999999999)"},"email":{"type":"string","description":"Email do contato"},"cpf":{"type":"string","description":"CPF do contato (formato: 000.000.000-00)"},"firstName":{"type":"string","description":"Primeiro nome do contato"},"lastName":{"type":"string","description":"Sobrenome do contato"},"businessName":{"type":"string","description":"Nome da empresa do contato"},"birthdayDate":{"type":"string","description":"Data de nascimento (formato: DD/MM/AAAA)"},"externalKey":{"type":"string","description":"Chave única do sistema para identificação (valor gerado do seu lado para controle do envio e não pode se repetir)"},"validateNumber":{"type":"boolean","description":"Validar numero (opcional, padrao true). Se false, usa o numero exatamente como enviado, sem normalizacao do 9o digito BR — recomendado p/ WABA evitar ticket duplicado"}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## GET /v2/api/external/{apiId}/getContactExtraInfo > GetContactExtraInfo ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/getContactExtraInfo":{"get":{"tags":["👤 Contatos"],"summary":"GetContactExtraInfo","operationId":"GetContactExtraInfo","parameters":[{"$ref":"#/components/parameters/ApiId"},{"name":"contactId","in":"query","required":false,"description":"ID do contato","schema":{"type":"integer"}}],"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/contacts/search > SearchContacts ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/contacts/search":{"post":{"tags":["👤 Contatos"],"summary":"SearchContacts","operationId":"SearchContacts","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"searchParam":{"type":"string","description":"Parâmetro de busca textual (opcional) - busca em nome, número, CPF, etc"},"page":{"type":"integer","description":"Número da página (padrão: 1)"},"limit":{"type":"integer","description":"Limite de resultados por página (padrão: 40)"},"tagId":{"type":"integer","description":"ID de uma tag para filtrar (opcional)"}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/showcontact > ShowContact ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/showcontact":{"post":{"tags":["👤 Contatos"],"summary":"ShowContact","operationId":"ShowContact","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"Número do WhatsApp do contato (formato: 5511999999999)"},"validateNumber":{"type":"boolean","description":"Validar numero (opcional, padrao true). Se false, usa o numero exatamente como enviado, sem normalizacao do 9o digito BR — recomendado p/ WABA evitar ticket duplicado"}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/updateContact > UpdateContact ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/updateContact":{"post":{"tags":["👤 Contatos"],"summary":"UpdateContact","operationId":"UpdateContact","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome completo do contato"},"number":{"type":"string","description":"Número do WhatsApp (formato: 5511999999999)"},"email":{"type":"string","description":"Email do contato"},"cpf":{"type":"string","description":"CPF do contato (formato: 000.000.000-00)"},"firstName":{"type":"string","description":"Primeiro nome do contato"},"lastName":{"type":"string","description":"Sobrenome do contato"},"businessName":{"type":"string","description":"Nome da empresa do contato"},"birthdayDate":{"type":"string","description":"Data de nascimento (formato: DD/MM/AAAA)"},"kanban":{"type":"integer","description":"ID do kanban do contato"},"externalKey":{"type":"string","description":"Chave única do sistema para identificação (valor gerado do seu lado para controle do envio e não pode se repetir)"},"validateNumber":{"type":"boolean","description":"Validar numero (opcional, padrao true). Se false, usa o numero exatamente como enviado, sem normalizacao do 9o digito BR — recomendado p/ WABA evitar ticket duplicado"}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/updateContactExtraInfo > UpdateContactExtraInfo ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/updateContactExtraInfo":{"post":{"tags":["👤 Contatos"],"summary":"UpdateContactExtraInfo","operationId":"UpdateContactExtraInfo","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"integer","description":"ID do contato que terá as informações adicionais atualizadas"},"extraInfo":{"type":"array","description":"Array de campos personalizados (extraInfo)","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/updateContactKanban > UpdateContactKanban ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/updateContactKanban":{"post":{"tags":["👤 Contatos"],"summary":"UpdateContactKanban","operationId":"UpdateContactKanban","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"integer","description":"ID do contato que terá o kanban (carteira) alterado"},"kanban":{"type":"integer","description":"ID do kanban (carteira) que será atribuído ao contato"}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/updateContactWallet > UpdateContactWallet ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/updateContactWallet":{"post":{"tags":["👤 Contatos"],"summary":"UpdateContactWallet","operationId":"UpdateContactWallet","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"integer","description":"ID do contato que será carteirizado"},"walletId":{"type":"integer","description":"ID da wallet que será atribuída ao contato (pode usar walletId ou walletIds)"}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/mergecontacts > MergeContacts ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/mergecontacts":{"post":{"tags":["👤 Contatos"],"summary":"MergeContacts","operationId":"MergeContacts","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pairs":{"type":"array","description":"Pares a mesclar (max 150 por requisicao — use chunking). Cada par aceita IDs OU numeros. Por numero: resolucao exato-primeiro; se ambiguo, a linha retorna ERR_NUMBER_AMBIGUOUS com os candidatos.","items":{"type":"object","properties":{"primaryId":{"type":"integer"},"duplicateId":{"type":"integer"}}}}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/findduplicatecontacts > FindDuplicateContacts ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/findduplicatecontacts":{"post":{"tags":["👤 Contatos"],"summary":"FindDuplicateContacts","operationId":"FindDuplicateContacts","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","description":"Limite de pares retornados (padrao 500)"},"matchKinds":{"type":"array","description":"Heuristicas (padrao: variante do 9o digito + cross-collision LID)","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` ## POST /v2/api/external/{apiId}/unmergecontacts > UnmergeContacts ```json {"openapi":"3.0.3","info":{"title":"Z-PRO — API Externa","version":"v4.x.x.x"},"tags":[{"name":"👤 Contatos"}],"servers":[{"url":"https://{baseUrl}","description":"Instalação Z-PRO do cliente","variables":{"baseUrl":{"default":"api.seudominio.com.br","description":"Domínio do backend Z-PRO, sem protocolo e sem barra final."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token da API do tenant (na coleção Postman: `BearerToken`)."}},"parameters":{"ApiId":{"name":"apiId","in":"path","required":true,"description":"ID da API externa cadastrada no Z-PRO.","schema":{"type":"string"}}}},"paths":{"/v2/api/external/{apiId}/unmergecontacts":{"post":{"tags":["👤 Contatos"],"summary":"UnmergeContacts","operationId":"UnmergeContacts","parameters":[{"$ref":"#/components/parameters/ApiId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"duplicateIds":{"type":"array","description":"Desfaz mesclagens registradas (ordem inversa: a mais recente primeiro). Max 150 por requisicao.","items":{"type":"integer"}},"mergeLogIds":{"type":"array","description":"Alternativa: ids do log de mesclagem","items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetros inválidos ou faltando."},"401":{"description":"Token ausente, inválido ou sem permissão."}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ajuda.zdg.com.br/central-do-assinante/referencia-da-api/contatos.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.