‌A API Contatos (VUC) permite o consumo de dados relativos aos contatos, documentos, comunicações e interações registrados dentro do produto Zenvia Docs, para alimentar sistemas internos e outras plataformas.

Possibilita a consulta de interações com a audiência através de chamada de API.

Esta API é dividida em quatro rotas:

Contatos: informações relativas aos dados de perfil, contatos e os documentos enviados ao contato pesquisado. A busca é realizada através do ID, CPF ou CNPJ do contato.
Comunicações: lista de comunicações enviadas para o usuário com base no customerId.
Interações: eventos das comunicações com base no shootingId.
Download de documentos: download de documentos por meio da sua externalKey.

Pontos importantes:

Esta API será cobrada como um serviço extra e as cobranças são feitas para cada chamada realizada;
As consultas de contatos devem ser feitas a partir de variáveis únicas, como ID, CPF ou CNPJ;
As consultas das comunicações devem ser feitas com base no customerId;
As consultas dos eventos das comunicações devem ser feitas com base no shootingId;
O download de documentos deve ser feito com base na externalKey;
Para obter este serviço, solicite ao time que o atende que ative e gere uma chave API para poder efetuar chamadas e consultar os dados da sua conta.

⚠️ Atenção: A API Contatos (VUC) retorna dados no formato JSON, no qual os campos possuem tamanho variável. Caso sua estrutura de banco de dados possua limitação de tamanho dos campos, recomendamos que os campos do tipo string sejam criados com o tamanho máximo suportado por sua estrutura de banco de dados.

⚓Request - Contatos

GET URL: https://apicore.d1.cx/vuc/v1/contact/{id/cpf/cnpj}

Obs.: Caso o CNPJ possua formatação, é preciso adicionar o encode da ”/”(%2F).

Parameters

Header

`TenantId`	string	Identificação do tenant
`Authorization`	string	Bearer <Token>
`Content-Type`	string	application/json

Queries

type string Tipo de consulta (ID, CPF ou CNPJ)

Responses

🟢 200 OK

`id`	string	Chave de identificação do customer
`name`	string	Nome
`birthDate`	date	Data de aniversário
`cnpj`	string	Cadastro Nacional de Pessoas Jurídicas
`cpf`	string	Cadastro de Pessoas Físicas
`rg`	string	Registro Geral
`credCard`	string	Números finais do cartão de crédito
`created`	date	Data de criação do contato
`emails`	list<email>	Lista de e-mails do customer
`email.address`	string	Endereço de e-mail
`email.kind`	string	Tipo e-mail
`phones`	list<phone>	Lista de telefones do customer
`phone.number`	string	Número de telefone
`phone.kind`	string	Tipo de telefone (fixo, celular)
`Addresses`	list<address>	Lista de endereços do customer
`address.street`	string	Descrição do endereço
`address.number`	string	Número do endereço
`address.complement`	string	Complemento do endereço
`address.neighborhood`	string	Bairro
`address.city`	string	Cidade
`address.state`	string	Sigla do Estado
`address.zipCode`	string	CEP
`address.kind`	string	Logradouro
`address.geoCode`	list<double>	Geolocalização/Coordenadas
`address.country.id`	string	Identificação do país de acordo com a ISO3166-1
`address.country.name`	string	Nome do país
`files`	list<file>	Lista de arquivos
`file.type`	string	Localização do arquivo, ou seja, onde ele está armazenado
`file.mode`	string	Indica a forma como o arquivo será disponibilizado dentro da comunicação
`file.isMain`	bool	Indica que é o arquivo principal dentro de um conjunto de arquivos enviados
`file.filename`	string	É o nome do arquivo
`file.description`	string	A descrição para um arquivo.
`file.correlationId`	string	É uma chave de identificação única do arquivo
`file.dueDate`	date	Data de vencimento do documento
`file.documentNumber`	string	Número do documento
`file.tag`	list<string>	Tags do documento
`file.movement.date`	datetime	Data do movimento
`file.movement.fileName`	string	Nome do movimento
`file.movement.lot`	string	Número do lote do documento
`file.storagePath`	string	É o caminho onde o documento está armazenado no storage
`file.link`	string	Link do arquivo
`file.groupDescription`	string	Descrição do arquivo
`file.ccmPdf`	bool	É o caminho onde o documento está armazenado no CCMPDF

 [{
     "id": "111.111.111-11",
     "name": "João da Silva",
     "birthDate": "1980-07-15T03:00:00.000Z",
     "cnpj": "22.333.333/4444-22",
     "cpf": "492.087.278-07",
     "rg": "12.345.678-0",
     "credCard": "345",
     "created": “2022-07-15T03: 00: 00.000Z”,
     "emails": [{
          "address": "[email protected]",
          "kind": "residential"
     }
     ],
     "phones": [{
          "number": "6135511902",
          "kind": "cellphone"
     }
     ],
     "addresses": [{
          "street": "Rua João da Silva Filho Junior",
          "number": "999",
          "complement": "Complemento",
          "neighborhood": "João da Silva Filho",
          "city": "São Paulo",
          "state": "SP",
          "zipCode": "12345-000",
          "country": {
          "id": "76",
          "name": "Brasil"
          },
          "kind": "residential",
          "geoCode": [
          -23.612667,
          -46.693859
          ]
     }
     ],
     "files": [{
          "type": "Storage",
          "mode": "Link",
          "isMain": true,
          "filename": "fatura directone",
          "description": "BOLETO",
          "correlationId": "46299F1DF4C9C9CCEDB4D49DAE6C254",
          "dueDate": "2021-02-01T03:00:00Z",
          "documentNumber": "1234567898524544",
          "tag": [
          “BOLETO”,
          “1VIA”
          ],
          "movement": {
          "date": "1980-07-15T03:00:00Z",
          "fileName": "abcd",
          "lot": "123"
          },
          "storagePath": "/meudiretorio",
          "link": "https://link.tipo.external",
          "groupDescription": "",
          "ccmPdf": false
     }]
   }
 ]

🟠 401: Unauthorized

 {
     "code": 401,
     "message": "Jwt is expired"
 }

 {
     "message": "Jwt is missing",
     "code": 401
 }
 {
     "type": "about:blank",
     "title": "Unauthorized",
     "status": 401,
     "detail": "Authorization error. Check if key 'TenantId' exist in request header and if its value is valid",
     "instance": "/v1/contact/11111111111/shooting/648c74dbb85f839dd295b7a0/interactions",
     "errorCode": "ERROR_UNAUTHORIZED",
     "traceId": "0HMRGN8FJHRS0:00000002"
 }

🟠 400: Bad Request

 {
     "type": "about:blank",
     "title": "BadRequest",
     "status": 400,
     "detail": "Query parameter 'type' is not valid.",
     "instance": "/v1/contact/123/",
     "traceId": "0HMRGO7NO6KJA:00000005",
     "tenantId": "123"
 }

 {
     "type": "about:blank",
     "title": "BadRequest",
     "status": 400,
     "detail": "The 'id' cannot be null or empty.",
     "instance": "/v1/contact/%20/",
     "errorCode": null,
     "traceId": "0HMRGO7NO6KJA:00000005",
     "tenantId": "123"
 }

🟠 500: Internal Server Error

 {
     "type": "about:blank",
     "title": "InternalServerError",
     "status": 500,
     "detail": "An error occurred while trying to get the data, contact us for support.",
     "instance": "/v1/contact/123/",
     "errorCode": "INTERNAL_SERVICE_ERROR",
     "traceId": "0HMRGOKBF2INH:00000002",
     "tenantId": "123"
 }

⚓Request - Comunicações

GET URL: https://apicore.d1.cx/vuc/v1/contact/{id}/communications

Obs.: Caso o ID seja um CNPJ e possua formatação, é preciso adicionar o encode da ”/”(%2F).

Parameters

Header

`TenantId`	string	Identificação do tenant
`Authorization`	string	Bearer <Token>
`Content-Type`	string	application/json

Query

lookbackDays integer Opcional. Define o período em dias para a busca. Se não for especificado, o padrão será 60 dias.
O valor máximo permitido também é 60 dias.

Responses

🟢 200 OK

`channel`	string	Canal de comunicação
`recipient`	string	Destinatário
`customerId`	string	Chave de identificação do customer
`journeyName`	string	Nome da jornada
`journeyVersion`	string	Versão da jornada
`journeyNodeKey`	string	Chave do canal da jornada
`journeyId`	string	Chave de identificação da jornada
`correlationId`	string	Identificador único do disparo
`shootingId`	string	Identificador do disparo

 [
   {
     "channel": "Sms",
     "recipient": "123456789",
     "customerId": "123",
     "journeyName": "Jornada Boleto",
     "journeyVersion": "543321",
     "journeyNodeKey":"111-222-333",
     "journeyId": "123",
     "correlationId": "123",
     "shootingId": "123"
   }
 ]

🟠 401: Unauthorized

 {
     "code": 401,
     "message": "Jwt is expired"
 }

 {
     "message": "Jwt is missing",
     "code": 401
 }

 {
     "type": "about:blank",
     "title": "Unauthorized",
     "status": 401,
     "detail": "Authorization error. Check if key 'TenantId' exist in request header and if its value is valid",
     "instance": "/v1/contact/11111111111/shooting/648c74dbb85f839dd295b7a0/interactions",
     "errorCode": "ERROR_UNAUTHORIZED",
     "traceId": "0HMRGN8FJHRS0:00000002"
 }

🟠 400: Bad Request

 {
     "type": "about:blank",
     "title": "BadRequest",
     "status": 400,
     "detail": "The 'id' cannot be null or empty.",
     "instance": "/v1/contact/%20/communications",
     "traceId": "0HMRGO7NO6KJA:00000005",
     "tenantId": "123"
 }

 {
    "type": "about:blank",
    "title": "BadRequest",
    "status": 400,
    "detail": "Days parameter must be at least 1.",
    "instance": "/v1/contact/123456/communications",
    "errorCode": "LOOKBACK_DAYS_INVALID",
    "traceId": "0HNF9AOV3A4LT:00000002",
    "tenantId": "123" 
 }

 {    
    "type": "about:blank",
    "title": "BadRequest",
    "status": 400,
    "detail": "Cannot retrieve data older than 60 days.",
    "instance": "/v1/contact/123456/communications",
    "errorCode": "LOOKBACK_DAYS_INVALID",
    "traceId": "0HNF9AOV3A4LU:00000002",
    "tenantId": "123"
}

🟠 500: Internal Server Error

 {
     "type": "about:blank",
     "title": "InternalServerError",
     "status": 500,
     "detail": "An error occurred while trying to get the data, contact us for support.",
     "instance": "/v1/contact/123/communications",
     "errorCode": "INTERNAL_SERVICE_ERROR",
     "traceId": "0HMRGOKBF2INH:00000002",
     "tenantId": "123"
 }

⚓Request - Interações

GET URL: https://apicore.d1.cx/vuc/v1/contact/{id}/shooting/{shootingId}/interactions

Obs.: Caso o ID seja um CNPJ e possua formatação, é preciso adicionar o encode da ”/”(%2F).

Parameters

Header

`TenantId`	string	Identificação do tenant
`Authorization`	string	Bearer <Token>
`Content-Type`	string	application/json

Query

lookbackDays integer Opcional. Define o período em dias para a busca. Se não for especificado, o padrão será 60 dias.
O valor máximo permitido também é 60 dias.

Responses

🟢 200 OK

`channel`	string	Canal de comunicação
`recipient`	string	Destinatário
`customerId`	string	Chave de identificação do customer
`journeyName`	string	Nome da jornada
`journeyVersion`	string	Versão da jornada
`journeyNodeKey`	string	Chave do canal da jornada
`journeyId`	string	Chave de identificação da jornada
`correlationId`	string	Identificador único do disparo
`shootingId`	string	Identificador do disparo
`eventType`	string	Tipo do evento
`date`	datetime	Data do evento
`response`	string	Texto de uma eventual resposta do destinatário para um SMS recebido
`bounce`	string	Descrição detalhada do motivo do bounce
`url`	string	Caso seja um evento de clique aqui, é apresentado o link clicado
`nodeName`	string	Nome do nó do canal
`channelCertificatedKind`	string	Tipo da certificação do canal
`channelCertificatedUrl`	string	URL do laudo da certificação do canal

 [
   {
     "channel": "Sms",
     "recipient": "123456789",
     "customerId": "123",
     "journeyName": "Jornada Boleto",
     "journeyVersion": "543321",
     "journeyNodeKey":"111-222-333",
     "journeyId": "123",
     "correlationId": "123",
     "shootingId": "123",
     "eventType": "Click",
     "date": "2022-07-15T03:00:00.000Z",
     "response": "teste",
     "bounce": "error",
     "url": "https://arquivo.clicado.com/123",
     "nodeName": "Email Boleto v1",
     "channelCertificatedKind": "None",
     "channelCertificatedUrl": "https://arquivo.certificado/123"
   }
 ]

🟠 401: Unauthorized

 {
     "code": 401,
     "message": "Jwt is expired"
 }

 {
     "message": "Jwt is missing",
     "code": 401
 }

 {
     "type": "about:blank",
     "title": "Unauthorized",
     "status": 401,
     "detail": "Authorization error. Check if key 'TenantId' exist in request header and if its value is valid",
     "instance": "/v1/contact/123/shooting/123/interactions",
     "errorCode": "ERROR_UNAUTHORIZED",
     "traceId": "0HMRGN8FJHRS0:00000002"
 }

🟠 400: Bad Request

 {
     "type": "about:blank",
     "title": "BadRequest",
     "status": 400,
     "detail": "The 'id' cannot be null or empty.",
     "instance": "/v1/contact/%20/shooting/123/interactions",
     "traceId": "0HMRGO7NO6KJA:00000005",
     "tenantId": "123"
 }

 {
     "type": "about:blank",
     "title": "BadRequest",
     "status": 400,
     "detail": "The 'shootingId' cannot be null or empty.",
     "instance": "/v1/contact/123/shooting/%20/interactions",
     "traceId": "0HMRGO7NO6KJA:00000005",
     "tenantId": "123"
 }

{
    "type": "about:blank",
    "title": "BadRequest",
    "status": 400,
    "detail": "Days parameter must be at least 1.",
    "instance": "/v1/contact/123456/shooting/123/interactions",
    "errorCode": "LOOKBACK_DAYS_INVALID",
    "traceId": "0HNF9AOV3A4LT:00000002",
    "tenantId": "123"
}

{
    "type": "about:blank",
    "title": "BadRequest",
    "status": 400,
    "detail": "Cannot retrieve data older than 60 days.",
    "instance": "/v1/contact/123456/shooting/123/interactions",
    "errorCode": "LOOKBACK_DAYS_INVALID",
    "traceId": "0HNF9AOV3A4LU:00000002",
    "tenantId": "123"
}

🟠 500: Internal Server Error

 {
     "type": "about:blank",
     "title": "InternalServerError",
     "status": 500,
     "detail": "An error occurred while trying to get the data, contact us for support.",
     "instance": "/v1/contact/123/shooting/123/interactions",
     "errorCode": "INTERNAL_SERVICE_ERROR",
     "traceId": "0HMRGOKBF2INH:00000002",
     "tenantId": "123"
 }

⚓Request - Download de documentos

GET URL: https://apicore.d1.cx/vuc/v1/document/{externalKey}

Parameters

Header

`TenantId`	string	Identificação do tenant
`Authorization`	string	Bearer <Token>
`Content-Type`	string	application/json

Response Status

Status	Descrição
🟢 200 OK	Requisição processada com sucesso.
🟠 401: Unauthorized	Acesso a API não foi autorizado. Verifique as credenciais de acesso ao serviço.
🟠 401: Not Found	A externalKey fornecida na requisição não foi encontrada
🔴 500: Internal Server Error	Falha interna da aplicação.

Response Body

🟢 200 OK

Retorna um arquivo, com o Header Content-Type = application/pdf.

🟠 401: Unauthorized

 {
     "code": 401,
     "message": "Jwt is expired"
 }

 {
     "message": "Jwt is missing",
     "code": 401
 }

{
     "type": "about:blank",
     "title": "Unauthorized",
     "status": 401,
     "detail": "Authorization error. Check if key 'TenantId' exist in request header and if its value is valid",
     "instance": "/v1/contact/11111111111/shooting/648c74dbb85f839dd295b7a0/interactions",
     "errorCode": "ERROR_UNAUTHORIZED",
     "traceId": "0HMRGN8FJHRS0:00000002"
 }

🟠 404: Not Found

 {
     "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
     "title": "Not Found",
     "status": 404,
     "traceId": "00-cf283f808fe81fa585fd46727c3060e0-ace9123413b91c1d-00"
 }

Como podemos ajudar?

⚓Request - Contatos

Parameters

Header

Queries

Responses

⚓Request - Comunicações

Parameters

Header

Responses

⚓Request - Interações

Parameters

Header

Responses

⚓Request - Download de documentos

Parameters

Header

Response Status

Response Body