# Oratrix API - Contatos ## Status Documentacao parcial baseada na parte enviada para o projeto Wezapp Shots. Este grupo e importante para preparacao de bases, sincronizacao de contatos e vinculacao de destinatarios em campanhas. ## Base URL ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID} ``` ## Autenticacao ```http Authorization: Bearer {token} ``` ## Endpoints do grupo Total documentado nesta parte: 9 endpoints. --- ## 1. Criar contato ```http POST /createContact ``` Nome na documentacao Oratrix: ```text CreateContact ``` Descricao: Criar um novo contato no sistema. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/createContact ``` Body JSON: ```json { "name": "Nome Completo", "number": "5511999999999", "email": "contato@email.com", "cpf": "000.000.000-00", "firstName": "Nome", "lastName": "Sobrenome", "businessName": "Empresa", "birthdayDate": "01/01/1990", "externalKey": "chave-001" } ``` Observacao para Wezapp Shots: O campo `externalKey` deve ser avaliado como chave de vinculacao entre contato interno do Wezapp e contato no Oratrix. --- ## 2. Buscar contato pelo numero ```http POST /showcontact ``` Nome na documentacao Oratrix: ```text ShowContact ``` Descricao: Buscar dados de um contato pelo numero do WhatsApp. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/showcontact ``` Body JSON: ```json { "number": "5511999999999" } ``` Observacao importante: A rota informada esta como `/showcontact`, com `c` minusculo. Manter exatamente esse path ate confirmacao oficial. --- ## 3. Atualizar contato ```http POST /updateContact ``` Nome na documentacao Oratrix: ```text UpdateContact ``` Descricao: Atualizar dados de um contato existente. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/updateContact ``` Body JSON: ```json { "name": "Nome Atualizado", "number": "5511999999999", "email": "novo@email.com", "cpf": "000.000.000-00", "firstName": "Nome", "lastName": "Sobrenome", "businessName": "Empresa", "birthdayDate": "01/01/1990", "kanban": 2, "externalKey": "ID_UNICA_SISTEMA" } ``` --- ## 4. Bloquear ou desbloquear contato ```http POST /blockContact ``` Nome na documentacao Oratrix: ```text BlockContact ``` Descricao: Bloquear ou desbloquear um contato. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/blockContact ``` Body JSON: ```json { "contactId": 1, "blocked": true } ``` Observacao para Wezapp Shots: Bloqueio/desbloqueio deve gerar auditoria local. Para opt-out, o Wezapp deve manter tambem um registro interno de bloqueio para nao depender apenas do estado externo. --- ## 5. Buscar contatos com filtros avancados ```http POST /contacts/search ``` Nome na documentacao Oratrix: ```text SearchContacts ``` Descricao: Buscar contatos com filtros avancados por texto, tag, wallet e bloqueado. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/contacts/search ``` Body JSON: ```json { "searchParam": "", "page": 1, "limit": 40, "tagId": null, "walletId": null, "blocked": false } ``` Observacao para Wezapp Shots: Este endpoint pode ser usado para conciliacao/sincronizacao, mas nao deve substituir a base interna de contatos do Wezapp. --- ## 6. Atualizar kanban do contato ```http POST /updateContactKanban ``` Nome na documentacao Oratrix: ```text UpdateContactKanban ``` Descricao: Atualizar o kanban/carteira de um contato. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/updateContactKanban ``` Body JSON: ```json { "contactId": 1, "kanban": 2 } ``` --- ## 7. Atribuir wallet ao contato ```http POST /updateContactWallet ``` Nome na documentacao Oratrix: ```text UpdateContactWallet ``` Descricao: Atribuir uma ou mais wallets a um contato. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/updateContactWallet ``` Body JSON: ```json { "contactId": 1, "walletId": 2 } ``` Observacao: A descricao fala em uma ou mais wallets, mas o exemplo mostra apenas `walletId` unico. Validar se a API aceita array. --- ## 8. Buscar campos personalizados do contato ```http GET /getContactExtraInfo ``` Nome na documentacao Oratrix: ```text GetContactExtraInfo ``` Descricao: Buscar campos personalizados `extraInfo` de um contato. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/getContactExtraInfo ``` Query params: | Parametro | Obrigatorio | Descricao | Exemplo | |---|---:|---|---| | contactId | Sim | ID do contato | 1 | --- ## 9. Atualizar campos personalizados do contato ```http POST /updateContactExtraInfo ``` Nome na documentacao Oratrix: ```text UpdateContactExtraInfo ``` Descricao: Atualizar campos personalizados de um contato. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/updateContactExtraInfo ``` Body JSON: ```json { "contactId": 1, "extraInfo": [ { "name": "Campo 1", "value": "Valor 1" }, { "name": "Campo 2", "value": "Valor 2" } ] } ``` ## Mapeamento sugerido com Wezapp Shots | Wezapp Shots | Oratrix | |---|---| | `wezapp_contacts.id` | ID interno do contato no Wezapp | | `wezapp_contacts.phone` | `number` | | `wezapp_contacts.name` | `name` | | `wezapp_contacts.email` | `email` | | `wezapp_contacts.document` | `cpf` | | `wezapp_contacts.metadata_json` | campos adicionais e retorno externo | | campo futuro `external_contact_id` | `contactId` no Oratrix | | campo futuro `external_key` | `externalKey` no Oratrix | ## Pendencias tecnicas para validar - Confirmar se `/showcontact` e exatamente o endpoint correto. - Confirmar se `externalKey` e unico no Oratrix. - Confirmar se `createContact` retorna `contactId`. - Confirmar comportamento ao criar contato duplicado pelo mesmo numero. - Confirmar formato aceito em `birthdayDate`. - Confirmar se `updateContactWallet` aceita multiplas wallets ou apenas uma. - Confirmar limite de `limit` em `/contacts/search`. - Confirmar formato do retorno de `extraInfo`. ## Regras recomendadas para o Wezapp Shots 1. Manter base interna de contatos no Wezapp. 2. Usar Oratrix como destino/sincronizacao operacional, nao como fonte unica de verdade. 3. Registrar `contactId` externo quando retornado. 4. Usar `externalKey` para rastreabilidade quando possivel. 5. Respeitar bloqueios internos antes de enviar contato ao Oratrix. 6. Registrar logs de criacao, atualizacao e bloqueio de contato.