{"openapi":"3.1.0","info":{"title":"Zyron Connect API","version":"1.1.0","description":"API pública para CRM, mensageria e vendas. Autenticação via Bearer zk_… (criada em Dashboard › API). Rate limit por chave e por plano: 120 req/min nos planos Básico e Oficial, 300 no Agency. Operações marcadas com x-availability indicam qual conexão atende: official (Meta), freemium (plano Básico) ou both."},"servers":[{"url":"https://connect.zyronstack.com/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"zk_live_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"next_offset":{"type":"integer","nullable":true}}}}},"security":[{"bearerAuth":[]}],"paths":{"/contacts":{"get":{"summary":"Lista contatos","parameters":[{"name":"stage_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"connection_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"phone","in":"query","schema":{"type":"string"}},{"name":"username","in":"query","schema":{"type":"string"}},{"name":"business_scoped_user_id","in":"query","schema":{"type":"string"}},{"name":"parent_business_scoped_user_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}},"post":{"summary":"Cria ou atualiza contato por identidade WhatsApp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection_id":{"type":"string","format":"uuid"},"phone":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"business_scoped_user_id":{"type":"string"},"parent_business_scoped_user_id":{"type":"string"},"stage_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Updated"},"201":{"description":"Created"}}}},"/contacts/{id}":{"get":{"summary":"Detalhe do contato (jornada + vendas)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}},"patch":{"summary":"Atualiza contato ou move etapa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/stages":{"get":{"summary":"Lista etapas do funil","responses":{"200":{"description":"OK"}}},"post":{"summary":"Cria etapa","responses":{"201":{"description":"Created"}}}},"/stages/{id}":{"patch":{"summary":"Atualiza etapa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}},"delete":{"summary":"Remove etapa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/sales":{"get":{"summary":"Lista vendas atribuídas (requer plano Oficial ou Agency)","x-availability":"both","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","paid","refunded","chargeback"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"403":{"description":"upgrade_required: recurso do plano Oficial/Agency"}}}},"/conversations":{"get":{"summary":"Lista conversas","parameters":[{"name":"connection_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"contact_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"phone","in":"query","schema":{"type":"string","description":"Telefone com DDI"}},{"name":"status","in":"query","schema":{"type":"string","enum":["open","closed","pending"]}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/conversations/resolve":{"get":{"summary":"Resolve conversa por conexão + identidade do destinatário","parameters":[{"name":"connection_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"phone","in":"query","schema":{"type":"string"}},{"name":"business_scoped_user_id","in":"query","schema":{"type":"string"}},{"name":"parent_business_scoped_user_id","in":"query","schema":{"type":"string"}},{"name":"username","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/conversations/{id}":{"get":{"summary":"Detalhe operacional da conversa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}},"patch":{"summary":"Atualiza status, tags, atendente ou nota interna","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/conversations/{id}/messages":{"get":{"summary":"Histórico de mensagens da conversa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":500}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/messages":{"get":{"summary":"Lista mensagens e estados do provider","parameters":[{"name":"connection_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"contact_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"provider_message_id","in":"query","schema":{"type":"string"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Envia mensagem WhatsApp tipada","description":"type=text funciona nas duas conexões; os demais tipos exigem conexão Oficial (Meta) e plano Oficial/Agency (403 upgrade_required abaixo disso). Limite por plano: 120 req/min (Básico/Oficial) ou 300 (Agency).","x-availability":"both","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["text","template","image","video","audio","document","sticker","location","contacts","interactive","reaction"],"default":"text"},"text":{"type":"string"},"template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"components":{"type":"array"}}},"media":{"type":"object","properties":{"id":{"type":"string"},"link":{"type":"string","format":"uri"},"caption":{"type":"string"},"filename":{"type":"string"}}},"location":{"type":"object"},"contacts":{"type":"array"},"interactive":{"type":"object"},"reaction":{"type":"object","properties":{"message_id":{"type":"string"},"emoji":{"type":"string"}}},"reply_to_message_id":{"type":"string"},"biz_opaque_callback_data":{"type":"string","maxLength":512,"description":"Correlação devolvida pela Meta nos status da mensagem."},"conversation_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". O número é comparado só pelos dígitos, aceita formatação e tolera a presença ou ausência do nono dígito brasileiro. Se o número corresponder a mais de uma conexão e não houver exatamente uma conectada, a resposta é 409 ambiguous_connection com a lista de candidates."},"from":{"type":"string","description":"Apelido de connection_id, para quem prefere pensar em número remetente."},"recipient":{"type":"object","description":"Informe ao menos uma identidade. Identidades sem phone são resolvidas no contato desta conexão; o envio falha se não houver telefone armazenado.","properties":{"phone":{"type":"string","description":"Telefone com DDI."},"contact_id":{"type":"string","format":"uuid"},"business_scoped_user_id":{"type":"string","description":"BSUID da Meta."},"parent_business_scoped_user_id":{"type":"string","description":"Parent BSUID da Meta."},"username":{"type":"string"}}},"to":{"type":"string","deprecated":true,"description":"Compatibilidade: equivalente a recipient.phone."}}}}}},"responses":{"202":{"description":"Accepted by Meta; inspect webhook/history for delivery"},"403":{"description":"upgrade_required: formato rico exige plano Oficial/Agency"},"404":{"description":"Not found"},"409":{"description":"ambiguous_connection: o número informado corresponde a mais de uma conexão"},"429":{"description":"Rate limited"}}}},"/messages/text":{"post":{"summary":"Envia mensagem de texto","description":"type é implícito. Mesmo núcleo de POST /messages; um type fora do conjunto desta rota responde 422 invalid_type.","x-availability":"both","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":4096},"conversation_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"from":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"recipient":{"type":"object","properties":{"phone":{"type":"string","description":"Telefone com DDI."},"contact_id":{"type":"string","format":"uuid"},"business_scoped_user_id":{"type":"string"},"parent_business_scoped_user_id":{"type":"string"},"username":{"type":"string"}}},"reply_to_message_id":{"type":"string"},"biz_opaque_callback_data":{"type":"string","maxLength":512}}}}}},"responses":{"202":{"description":"Accepted by Meta; inspect webhook/history for delivery"},"403":{"description":"upgrade_required: formato rico exige plano Oficial/Agency"},"404":{"description":"Not found"},"409":{"description":"ambiguous_connection: o número informado corresponde a mais de uma conexão"},"422":{"description":"invalid_type ou destino incompleto"},"429":{"description":"Rate limited"}}}},"/messages/media":{"post":{"summary":"Envia imagem, vídeo, áudio, documento ou figurinha","description":"type é obrigatório e define qual mídia está sendo enviada. Mesmo núcleo de POST /messages; um type fora do conjunto desta rota responde 422 invalid_type.","x-availability":"official","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["image","video","audio","document","sticker"]},"media":{"type":"object","properties":{"id":{"type":"string"},"link":{"type":"string","format":"uri"},"caption":{"type":"string"},"filename":{"type":"string"}}},"conversation_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"from":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"recipient":{"type":"object","properties":{"phone":{"type":"string","description":"Telefone com DDI."},"contact_id":{"type":"string","format":"uuid"},"business_scoped_user_id":{"type":"string"},"parent_business_scoped_user_id":{"type":"string"},"username":{"type":"string"}}},"reply_to_message_id":{"type":"string"},"biz_opaque_callback_data":{"type":"string","maxLength":512}}}}}},"responses":{"202":{"description":"Accepted by Meta; inspect webhook/history for delivery"},"403":{"description":"upgrade_required: formato rico exige plano Oficial/Agency"},"404":{"description":"Not found"},"409":{"description":"ambiguous_connection: o número informado corresponde a mais de uma conexão"},"422":{"description":"invalid_type ou destino incompleto"},"429":{"description":"Rate limited"}}}},"/messages/template":{"post":{"summary":"Envia template aprovado pela Meta","description":"type é implícito. Mesmo núcleo de POST /messages; um type fora do conjunto desta rota responde 422 invalid_type.","x-availability":"official","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"components":{"type":"array"}}},"conversation_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"from":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"recipient":{"type":"object","properties":{"phone":{"type":"string","description":"Telefone com DDI."},"contact_id":{"type":"string","format":"uuid"},"business_scoped_user_id":{"type":"string"},"parent_business_scoped_user_id":{"type":"string"},"username":{"type":"string"}}},"reply_to_message_id":{"type":"string"},"biz_opaque_callback_data":{"type":"string","maxLength":512}}}}}},"responses":{"202":{"description":"Accepted by Meta; inspect webhook/history for delivery"},"403":{"description":"upgrade_required: formato rico exige plano Oficial/Agency"},"404":{"description":"Not found"},"409":{"description":"ambiguous_connection: o número informado corresponde a mais de uma conexão"},"422":{"description":"invalid_type ou destino incompleto"},"429":{"description":"Rate limited"}}}},"/messages/interactive":{"post":{"summary":"Envia botões, listas e demais formatos interativos","description":"type é implícito. Localização, contatos e reação usam POST /messages. Mesmo núcleo de POST /messages; um type fora do conjunto desta rota responde 422 invalid_type.","x-availability":"official","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"interactive":{"type":"object"},"conversation_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"from":{"type":"string","description":"UUID da conexão (GET /connections) ou o número da instância, ex.: \"556293663491\". Também aceito no campo from."},"recipient":{"type":"object","properties":{"phone":{"type":"string","description":"Telefone com DDI."},"contact_id":{"type":"string","format":"uuid"},"business_scoped_user_id":{"type":"string"},"parent_business_scoped_user_id":{"type":"string"},"username":{"type":"string"}}},"reply_to_message_id":{"type":"string"},"biz_opaque_callback_data":{"type":"string","maxLength":512}}}}}},"responses":{"202":{"description":"Accepted by Meta; inspect webhook/history for delivery"},"403":{"description":"upgrade_required: formato rico exige plano Oficial/Agency"},"404":{"description":"Not found"},"409":{"description":"ambiguous_connection: o número informado corresponde a mais de uma conexão"},"422":{"description":"invalid_type ou destino incompleto"},"429":{"description":"Rate limited"}}}},"/messages/{id}":{"get":{"summary":"Detalhe de mensagem com payload do provider","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/messages/{id}/read":{"post":{"summary":"Marca mensagem inbound como lida","x-availability":"official","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"422":{"description":"Unsupported for connection"}}}},"/media":{"post":{"summary":"Faz upload de mídia para uma conexão Oficial da Meta (plano Oficial/Agency)","x-availability":"official","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["connection_id","file"],"properties":{"connection_id":{"type":"string","format":"uuid","description":"Conexão Oficial dona da mídia."},"file":{"type":"string","format":"binary","description":"Arquivo até 100 MB; limites de formato da Meta se aplicam."}}}}}},"responses":{"201":{"description":"Media uploaded; use data.id in messages"},"403":{"description":"upgrade_required"},"422":{"description":"Invalid file or unsupported connection"}}}},"/media/{id}":{"get":{"summary":"Consulta metadados e URL de download autenticada","x-availability":"official","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Meta media ID"},{"name":"connection_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Metadata and Zyron download URL"},"403":{"description":"upgrade_required"},"404":{"description":"Not found"}}},"delete":{"summary":"Remove mídia da Meta","x-availability":"official","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"}}}},"/media/{id}/download":{"get":{"summary":"Baixa o binário de mídia sem expor token Meta","x-availability":"official","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Binary response with original content type"}}}},"/connections":{"get":{"summary":"Lista conexões WhatsApp e capacidades","description":"phone_number vem no formato devolvido pelo provedor; phone_number_digits é o mesmo número normalizado e é o valor que as rotas de envio e os filtros por conexão aceitam no lugar do connection_id.","responses":{"200":{"description":"OK"}}}},"/connections/{id}":{"get":{"summary":"Detalhe de conexão e capacidades","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/connections/{id}/health":{"get":{"summary":"Saúde e limites do número Oficial (qualidade, tier, throughput, health_status)","x-availability":"official","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"403":{"description":"upgrade_required"},"422":{"description":"Conexão não é Oficial"}}}},"/connections/{id}/profile":{"get":{"summary":"Perfil de negócio do número Oficial","x-availability":"official","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"403":{"description":"upgrade_required"},"422":{"description":"Conexão não é Oficial"}}},"patch":{"summary":"Atualiza o perfil de negócio (somente campos enviados)","x-availability":"official","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string","maxLength":139},"address":{"type":"string","maxLength":256},"description":{"type":"string","maxLength":512},"email":{"type":"string","format":"email"},"vertical":{"type":"string","description":"Catálogo da Meta (RETAIL, PROF_SERVICES, HEALTH…)"},"websites":{"type":"array","maxItems":2,"items":{"type":"string","format":"uri"}}}}}}},"responses":{"200":{"description":"Perfil atualizado"},"403":{"description":"upgrade_required"},"422":{"description":"Campo inválido ou conexão não Oficial"}}}},"/templates":{"get":{"summary":"Lista templates locais e status de aprovação","x-availability":"official","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","pending","approved","rejected"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK"}}}},"/webhooks":{"get":{"summary":"Lista configurações do webhook de saída (uma por conexão)","x-availability":"both","parameters":[{"name":"connection_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Configurações + catálogo structured_events"}}},"put":{"summary":"Cria/atualiza o webhook de saída de uma conexão","x-availability":"both","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connection_id","url"],"properties":{"connection_id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"Endpoint http(s) que recebe os eventos."},"events":{"type":"array","items":{"type":"string"},"description":"Eventos assinados; vazio assina todos. Aceita whatsapp.message.received|sent|delivered|read|failed, whatsapp.connection.updated e os nomes nativos do provider."},"secret":{"type":"string","description":"Segredo do HMAC x-zyron-signature. Gerado quando ausente."},"active":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Atualizado"},"201":{"description":"Criado"},"422":{"description":"URL ou evento inválido"}}},"delete":{"summary":"Desativa o webhook de saída de uma conexão","x-availability":"both","parameters":[{"name":"connection_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Desativado"},"404":{"description":"Não configurado"}}}},"/webhooks/deliveries":{"get":{"summary":"Histórico de entregas do webhook (status, tentativas, erros)","x-availability":"both","parameters":[{"name":"connection_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","delivered","failed","dead"]}},{"name":"event","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK"}}}},"/webhook-events":{"get":{"summary":"Lista eventos brutos recebidos dos providers","x-availability":"both","parameters":[{"name":"connection_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"query","schema":{"type":"string","enum":["meta","freemium"]}},{"name":"event","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK"}}}}}}