O acesso a este documento não deve ser compartilhado com clientes, pois uma parte desta API ainda não possui autenticação
O Citrus é uma plataforma de comunicação omnichannel personalizável, que unifica canais de atendimento físicos e digitais. Com foco na experiência do cliente, o Citrus fornece ferramentas para um serviço otimizado e eficiente.
\n\n\nSaiba mais sobre o Citrus.
\n
O Citrus pode ser integrado a outras plataformas via API, através da Citrus.cx API. Ela facilita a criação e o gerenciamento dos pontos de contato da jornada do cliente.
\nConfira como abrir um atendimento através da Citrus.cx API.
\n","_postman_id":"a393fee0-f4e4-4836-ac6f-c92858970a85"},{"name":"Pré-requisitos","item":[],"id":"9ae48f6a-de87-4591-89f3-52da05f814b8","description":"Para acessar a API é necessário ser usuário da plataforma Citrus.
\n\n\nVerifique como criar uma conta no Citrus.
\n
O path para fazer requisições usando a Citrus.cx API é o URL customizado da empresa no Citrus, somado a /api/ no final do endereço. Exemplo: https://empresa.citrus.cx/api/.
As chamadas devem ser feitas usando o protocolo HTTPS.
\n","_postman_id":"9ae48f6a-de87-4591-89f3-52da05f814b8"},{"name":"Abertura de atendimento","item":[{"name":"Abertura de atendimento","id":"f586bb87-fc29-4901-9e42-f43cf4ef2727","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"userCreated\": \"898922\",\r\n \"description\": \"Atualização de dados cadastrais do cliente\",\r\n \"occurrence\": \"770458\",\r\n \"channel\": \"1\",\r\n \"clientCode\": \"999111232\",\r\n \"clientType\": \"1\",\r\n \"clientRegion\": \"7ae67e86-250b-6506-d18e-0c863364bbd0\",\r\n \"clientName\": \"João Paulo da Silva\",\r\n \"clientEmail\": \"jps@email.com\",\r\n \"clientPhone\": \"(83) 4001-9999\",\r\n \"clientCellphone\": \"(83) 99999-0000\",\r\n \"attachments\": [\r\n { \"url\": \"http://localhost/file.pdf\", \"filename\": \"file.pdf\" }, \r\n { \"url\": \"http://localhost/file2.pdf\", \"filename\": \"file2.pdf\" }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://empresa.citrus.cx/api/atendimentos","description":"Para abrir um atendimento com o cliente, chame POST /atendimentos e preencha o corpo da requisição no formato JSON com os seguintes campos:
Feita a requisição, haverá duas possibilidades de resposta.
\nA resposta do código 200 indica que os dados foram preenchidos corretamente e o sistema retornará um JSON com o número do Protocolo.
Exemplo:
\n{ \n\"protocol\" : \"123456\" \n} \n\nCaso os dados estejam incorretos ou aconteça alguma falha na abertura da chamada, a API retornará o código 400 e um JSON indicando os campos inválidos.
Exemplo:
\n{ \n\"errors\": [\n{\n\"error\": \"Código do usuário inválido\"\n},\n{\n\"error\": \"Código da ocorrência inválido\"\n},\n{\n\"error\": \"Código do canal inválido\"\n}\n] \n} \n\nPara consultar um status de atendimento, é necessário que o usuário tenha em seu perfil a permissão Consultar status de atendimento via API. O caminho para liberar esse acesso é Administração > Usuários > Perfil > (escolha o perfil desejado) > (habilitar a permissão) Consultar status de atendimento via api.
\nPara alterar um status de atendimento, é necessário que o usuário tenha em seu perfil a permissão Alterar status de atendimento via API. O caminho para liberar esse acesso é Administração > Usuários > Perfil > (escolha o perfil desejado) > (habilitar a permissão) Alterar status de atendimento via api.
\n\n\nObservação: Para que seja possível visualizar essa permissão de acesso, um usuário Administrador (com permissões root) deve habilitá-la para os demais usuários na hierarquia em Administração > Usuários > Perfil > (escolha o perfil desejado) > (habilitar a permissão).
\n
Também é preciso ter motivos cadastrados na tela Motivo (Administração > Configurações Gerais > Motivo).
\n","_postman_id":"5b172a81-5ea7-47b4-bad4-bdaeb04e5707"},{"name":"Autenticação","item":[{"name":"Autenticação","id":"cf113e23-d5c8-4ae3-b890-ea4c288bf92c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n\"login\": \"canaldenuncia\",\r\n\"senha\": \"&xFSn7a%S2dy$wa5DWhgZx\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://canaldenuncia-digivox.citrus.cx/api/usuario/login","urlObject":{"protocol":"https","path":["api","usuario","login"],"host":["canaldenuncia-digivox","citrus","cx"],"query":[],"variable":[]}},"response":[{"id":"8f0fc981-38c2-4237-b4d6-0a03cc9ef2e0","name":"200 - OK","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{ \r\n “login”: “user.api”, \r\n “senha”: “1234”\r\n} ","options":{"raw":{"language":"json"}}},"url":"https://empresa.citrus.cx/api/usuario/login"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{ \r\n “access-token”: “a00BCd0000-EF0g00b0HI00j0K0.LM0n0000” \r\n} "},{"id":"41877782-4a0b-4fbc-b153-7a7a302d7809","name":"404 - Usuário não encontrado ou senha inválida","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{ \r\n “login”: “user.api”, \r\n “senha”: “1234”\r\n}","options":{"raw":{"language":"json"}}},"url":"https://empresa.citrus.cx/api/usuario/login"},"status":"Not Found","code":404,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{ \r\n “error”: “Usuário não encontrado” \r\n} "},{"id":"28406dc7-9a2b-4fcb-b1c0-d05e4a24803a","name":"400 - Login e/ou senha ausente(s)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{ \r\n “login”: “”, \r\n “senha”: “” \r\n}","options":{"raw":{"language":"json"}}},"url":"https://empresa.citrus.cx/api/usuario/login"},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{ \r\n “errors”: [ \r\n { \r\n “error”: “Este campo é obrigatório - login” \r\n }, \r\n { \r\n “error”: “Este campo é obrigatório - senha” \r\n } \r\n ] \r\n} "},{"id":"8e064a99-ad6c-4b1b-8688-eb736da419ac","name":"500 - Erro do servidor","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{ \r\n “login”: “user.api”, \r\n “senha”: “1234”\r\n}","options":{"raw":{"language":"json"}}},"url":"https://empresa.citrus.cx/api/usuario/login"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{ \r\n “error”: “Houve um problema ao gerar o token” \r\n} "}],"_postman_id":"cf113e23-d5c8-4ae3-b890-ea4c288bf92c"}],"id":"fb14cde8-a1ad-4a7f-8788-e5cbd92704ec","description":"Antes de utilizar os endpoints de consulta e alteração de status de atendimento, o usuário precisa ser autenticado. Para autenticar, chame POST /usuario/login preenchendo o corpo da requisição com os seguintes campos:
Feita a requisição, haverá as seguintes possibilidades de resposta:
\nA resposta do código 200 indica que os dados foram preenchidos corretamente e o sistema retornará um JSON com o access-token.
{ \n “access-token”: “a00BCd0000-EF0g00b0HI00j0K0.LM0n0000” \n} \n\nCaso aconteça alguma falha na abertura da chamada, a API pode retornar os seguintes códigos de erro:
\n404 Usuário não encontrado ou senha inválida
{ \n “error”: “Usuário não encontrado” \n} \n\n400 Login e/ou senha ausente(s)
{ \n “errors”: [ \n { \n “error”: “Este campo é obrigatório - login” \n }, \n { \n “error”: “Este campo é obrigatório - senha” \n } \n ] \n} \n\n500 Erro do servidor
{ \n “error”: “Houve um problema ao gerar o token” \n} \n\nSe houver algum problema com o access-token durante as chamadas GET e PUT, a API pode retornar os seguintes códigos de erro:
401 Requisição feita sem access-token
{ \n “error”: “token is missing” \n} \n\n401 access-token expirado
{ \n “error”: “JWT expired at 2024-05-05T19: 42: 13Z. Current time: 2024-05-05T19: 49: 11Z, a difference of 418767 milliseconds. Allowed clock skew: 0 milliseconds.” \n} \n\n401 access-token com falha
{ \n “error”: “JWT signature does not match locally computed signature. JWT validity cannot be asserted and should not be trusted.” \n} \n\nPara consultar status de um protocolo de atendimento na plataforma, chame GET /atendimentos/status/numerodoprotocolo, em que numerodoprotocolo deve informar o número do protocolo do Citrus para realizar a consulta.
Esta chamada poderá ser feita para consultar protocolos de atendimento com os seguintes status:
\nAberto
\nEm atendimento
\nCancelado
\nImprocedente
\nFinalizado
\nAguardando retorno
\nFeita a requisição, haverá as seguintes possibilidades de resposta:
\nA resposta do código 200 indica que a consulta foi realizada e o sistema retornará um JSON com o número do protocolo e o status do atendimento.
{ \n“protocolo”: “202401023000004”, \n“status”: “Finalizado” \n} \n\nCaso aconteça alguma falha na abertura da chamada, a API pode retornar os seguintes códigos de erro:
\n404 Atendimento não encontrado
{ \n \"error”: “Atendimento não encontrado” \n} \n\n403 Acesso negado
{ \n “error”: “access denied” \n} \n\nPara alterar um status de atendimento, chame PUT /atendimentos/status e preencha os campos abaixo:
Os status possíveis de alteração são:
\nEm atendimento
\nCancelado
\nImprocedente
\nFinalizado
\nAberto
\nExemplo de chamada com os campos preenchidos:
\n{ \n “protocolo”: “20221104000001”, \n “status”: “Finalizado”, \n “motivoStatus: ”Atendimento já finalizado” \n “comentario: ”Comentário de atendimento” \n “visivelCliente: ”true” \n} \n\nFeita a requisição, haverá as seguintes possibilidades de resposta:
\nA resposta do código 200 indica que o atendimento foi atualizado.
{ \n “message”: “Atendimento atualizado com sucesso” \n} \n\nCaso aconteça alguma falha na abertura da chamada, a API pode retornar os seguintes códigos de erro:
\n404 Atendimento não encontrado
{ \n \"error”: “Atendimento não encontrado” \n} \n\n404 Status não encontrado
{ \n “error”: “Status não encontrado” \n} \n\n400 Motivo requerido
{ \n “errors”: [ \n { \n “error”: “motivoStatus - este campo é obrigatório” \n } \n ] \n} \n\nPara consultar ou alterar um status de atendimento, é necessário seguir alguns passos antes.
\n","_postman_id":"082cc042-7a31-4ead-bb3c-743125a5f876"}]}