Envio de dados por API
Esta documentação tem como objetivo apresentar os principais serviços da Carol para criar uma integração para o envio de dados para Carol. Ele também abrange o processo de consumo de dados e o entendimento de como extrair dados do Golden Records.
Swagger
O Swagger é uma estrutura que permite aos desenvolvedores projetar, criar, documentar e consumir a API REST
A Carol provê o acesso ao Swagger através de duas URLs:
Provê acesso aos serviços necessários para a integração de qualquer aplicativo com Carol, aproveitando ao máximo processos como autenticação, ingestão e consumo de dados.
Provê acesso aos serviços necessários para que recursos avançados na integração com a Carol sejam possíveis. Aqui há serviços ligados à Carol Apps, processamento de dados, segurança, privacidade de dados, entre outros. Boa parte dos serviços disponíveis nesta seção já estão disponíveis na plataforma Carol através de fluxos de UI.
Autenticação usuário/senha
Abaixo é listado os principais serviços ligados ao fluxo OAuth:
Esses serviços permitem efetuar a autenticação na Carol e efetuar a validação de um token já existente. Vamos ver os detalhes desses serviços:
/api/v1/oauth2/token
Este endpoint permite efetuar a autenticação na Carol, validando se o usuário e a senha possuem acesso à plataforma. Abaixo é detalhado os parâmetros necessários:
| Parâmetro | Valor |
|---|---|
| grant_type | Este parâmetro aceita um dos seguintes valores: password ou refresh_token. Password é utilizado no fluxo de geração do token, enquanto refresh_token é utilizado par renovar um token já existente. |
| username | Usuário que está no processo de autenticação. |
| password | Senha do usuário no fluxo de autenticação. |
| refresh_token | Utilizado apenas quando grant_type for refresh_token, este parâmetro espera o refresh_token para gerar um novo token. |
| subdomain | Este parâmetro é o nome do ambiente (antes chamado de Tenant). O nome do ambiente é parte da URL, e pode ser obtido da seguinte forma: "totvs.carol.ai/production", o nome do ambiente é production. |
| orgSubdomain | Nome da organização. Este parâmetro espera o mesmo nome definido como subdomínio da URL da Carol. Por exemplo, "totvs.carol.ai/production, o nome da organização é "totvs." |
| connectorId | Este parâmetro recebe o código do conector (connectorID) ou o nome do conector (visualizado na URL ou nos detalhes do conector). |
Abaixo é um exemplo da request usando o comando curl:
curl -X POST "https://api.carol.ai/api/v1/oauth2/token" -H "accept: application/json" -H "content-type: application/x-www-form-urlencoded" -d "grant_type=password&connectorId=clockinmobile&username=robson.poffo%40totvs.com&password=SENHA_AQUI&subdomain=poffo&orgSubdomain=poffo"
O resultado da request é semelhante ao abaixo:
{ "access_token": "ACCESS_TOKEN", "client_id": "4c2c9090e7c611e893bf0e900682978b_33dd1190ff2c11e8858be609736e2a59_c1367ca0e86311e8b979aedbc4a09666_mdmConnector", "expires_in": 3495, "refresh_token": "REFRESH_TOKEN", "state": "", "timeIssuedInMillis": 1591855130722, "token_type": "bearer" }
/api/v1/oauth2/token/{access_token}/userAccessDetails
Este endpoint permite resgatar detalhes referente ao token, inclusive verificar se o token ainda esta válido:
| Parâmetro | Valor |
|---|---|
| access_token | Access token gerado pelo endpoint "token". |
Abaixo é um exemplo da request usando o comando curl:
curl -X GET "https://api.carol.ai/api/v1/oauth2/token/TOKEN_AQUI/userAccessDetails" -H "accept: application/json"
O resultado da request é semelhante ao abaixo:
{ "envUserId": "c1367ca0e86311e8b979aedbc4a09666", "externalAppId": "33dd1190ff2c11e8858be609736e2a59", "loginLevel": "mdmTenant", "orgId": "856e0510729e11e99928acde48001122", "refreshToken": "1fd8bc5763734ad0b8e18e2cd328f2f8", "system": false, "tenantId": "4c2c9090e7c611e893bf0e900682978b", "userId": "fe115382754247d883d9a11b88b3d96e" }
Depois que a autenticação ocorrer, teremos access_token disponível. Este valor deve ser inserido no swagger no atributo Access Token (parte superior central).
Abaixo é um exemplo de uma request autenticada:
curl -X GET "https://api.carol.ai/api/v1/users?pageSize=10&sortOrder=ASC" -H "accept: application/json" -H "Authorization: TOKEN_AQUI"
Autenticação connector token
Além do processo convencional de autenticação do processo OAuth, é possível fazer a geracão de um token persistente. Este token é chamado de "Connector Token", e o mesmo é utilizado principalmente em integração de processos sendo que é utilizado uma chave pública e uma chave privada, conforme detalhado a seguir:
Sendo que já efetuamos o login na plataforma, vamos acessar item Tenant Admin no menu lateral (primeiro ícone no cabeçalho, da direita para a esquerda):
Após acessar Tenant Admin, clique na aba Tokens, a tela abaixo irá aparecer. Nesta tela podemos consultar todos os tokens disponíveis neste ambiente. Lembrando que não é possível ver o token gerado anteriormente - ele está disponível apenas logo após a criação.
A criação de novos tokens ocorre pelo botão Create token (na tela acima). Na tela que será aberta, você deverá selecionar o tipo de Token a ser criado:
- Carol Token: utilizado para comunicação através de API key com a Carol.
- Google Service Account: token de comunicação diretamente com os serviços da Google (Bigquery).
Selecionando a opção Carol Token, você deverá selecionar o conector que será utilizado para criar o token, também é possível adicionar uma descrição para revisão futura deste token.
Ao término destes passos a tela abaixo será apresentada. Você deverá guardar as seguintes informações para utilizar nas requests à plataforma:
Abaixo é um exemplo de uma request autenticada:
curl -X GET "https://api.carol.ai/api/v1/users?pageSize=10&sortOrder=ASC" -H "accept: application/json" -H "X-Auth-ConnectorId: CONNECTOR_ID_AQUI" -H "X-Auth-Key: CONNECTOR_TOKEN_AQUI"
Envio de dados
A Carol possui autenticação OAuth, podendo ser explorado a autenticação API Key (também conhecido como API Token ou Connector Token).
Abaixo é listado os principais serviços ligados ao fluxo staging area:
Esses serviços permitem efetuar a definição da estrutura de dados (schema), efetuar o envio de dados bem como eliminação de dados e eliminação da staging table na Carol.
Definindo schema da staging table
Todos os dados enviados para a Carol devem possuir um schema, que é basicamente a definição da estrutura que será armazenado na Carol. O conceito do schema segue o mesmo princípio do schema de tabelas em banco de dados relacional.
O seguinte schema é um exemplo de como a definição ocorre na plataforma Carol:
{
"mdmFlexible":"false",
"mdmExportData":"false",
"mdmStagingMapping":{
"properties":{
"cod-emitente":{
"type":"integer"
},
"cgc":{
"type":"string"
},
"nome-emit":{
"type":"string"
}
}
},
"mdmCrosswalkTemplate":{
"mdmCrossreference":{
"emitente":[
"cod-emitente"
]
}
}
}
O identifier (chamado também de crosswalk) é a definição da chave primária de uma staging table. O identifier na Carol funciona com o objetivo de atualizar um registro na staging area, fazendo com que um registro já existente seja atualizado por novos valores. O identifier também é utilizado no processo de eliminação de registros, como veremos um pouco mais para frente.
Criando uma staging table
O Json definido na etapa anterior deve ser enviado no endpoint abaixo para efetuar a criação da staging table:
Tabelas do Protheus devem sempre seguir as chaves primárias (PKs / crosswalk) conforme definido na tabela X2 do Protheus. O schema também deve ser conforme definição padrão do Protheus.
Caso a tabela em especifico não possua a chave primária definida na tabela X2, o dono do produto deverá ser consultado para definição da chave primária a ser assumido.
Definições sem o prévio alinhamento podem causar impactos no aplicativo por definições inconsistente para a mesma tabela.
Atualizando uma staging table
O endpoint abaixo permite atualizar o schema da staging table. O schema segue o mesmo podemo visualizado em Definindo schema da staging table:
Obs.: O schema da staging table pode ser ajustado através da interface gráfica da Carol.
Removendo uma staging table
O endpoint abaixo permite a eliminação de staging table através do nome da staging table:
Enviando dados para a Carol
A staging table possui o objetivo de armazenar dados (registros/documentos) na sua estrutura. O serviço abaixo é o responsável por receber um conjunto de dados (array de documentos JSON). Conforme definido no capítulo anterior, o atributo identifier irá determinar se os registros serão adicionados na Carol ou se eles irão atualizar dados já existentes.
Observação: recomenda-se o envio de dados através da rota intake: /api/v3/staging/intake/{table}
Os parâmetros batchId e batchIdSequence são utilizados para tracking dos dados no recebimento, armazenamento e processamento dos dados. O parâmetro batchId representa um pacote de dados que estão sendo enviados (ou que foram enviados) por um conector para a plataforma Carol.
O envio de dados através do endpoint intake pode ocorrer para diversas entidades dentro do mesmo batchId, isso quer dizer que a plataforma não vai iniciar o processamento de dados enquanto o pacote inteiro não for completamente recebido, para evitar processamento de dados enquanto os dados estão parcialmente disponíveis na plataforma Carol.
Quando o conector chamar o endpoint summary (/api/v3/staging/batch/{batchId}/summary) encerrando o batchId indicará para a plataforma iniciar o processamento dos dados. Veja o capítulo da Eficiência do SQL Processing para maiores detalhes.
Atualmente apenas o ERP Protheus está compativel com o envio de dados através de batchId. Apenas releases de Outubro/2023 e superiores estão homologados.
Os dados armazenados na plataforma Carol possuem a característica de serem imutáveis, o que faz com que a Carol armazene todas as versões que o dado sofreu durante as atualizações do registro. Em outras palavras, quando um dado é alterado a plataforma preservará as duas versões (antes de atualização e a versão mais recente).
A plataforma possui o processo de consolidação para que versões anteriores do registro sejam descartados. Este processo pode ser agendado para execução frequente e automática.
O serviço acima descrito permite o envio de dados seguinte a RFC1952 que permite o envio de dados compactados. Altamente recomendado que os dados sejam enviados desta forma, reduzindo assim o tempo de latência na requisição.
A request de envio de dados permite a utilização do nome do conector no parâmetro "connectorId" tornando o aplicativo mais simples e menos dependente ao ambiente do cliente. O nome do conector pode ser obtido na tela de "Connectors" na Carol.
O nome da tabela deve possuir caracteres e número, sendo obrigatório iniciar com um caracter. Caracteres especiais não são permitidos.
O body deve ser um array de objetos Json seguindo o schema definido para a staging table no passo anterior.
Vale ressaltar que este serviço efetua o envio dos dados através de uma requisição assíncrona. Isso quer dizer que quando o serviço responder o código 200, os dados não estarão disponíveis na staging table ou no data model (explore), alguns segundos podem ser necessários para que isso ocorrá.
Enviando o sumário de um batchId
Este endpoint é necessário apenas quando o envio de dados ocorre através do endpoint de intake informando o batchId.
Este é o formato do Json esperado no endpoint:
{
"totalRecords": 6,
"totalRequests": 2,
"timestampEnd": "2023-12-04T19:15:30Z",
"timestampStart": "2023-12-04T18:15:30Z"
}
Assinatura do endpoint:
POST /api/v3/staging/batch/{batchId}/summary
Este endpoint foi desenhado para ser chamado ao concluir o envio de dados para a plataforma Carol, independentemente de quantas tabelas forem enviado os dados.
O sumário é encerrado automaticamente pela plataforma Carol em 30 minutos após o envio do último dado pelo endpoint intake. E com o encerramento do batchId (pelo sumário ou por timeout) é iniciado o processamento dos dados.
Eliminando dados através da staging area
Este serviço possui o objetivo de eliminar dados na Carol, através dos valores dos atributos definidos como identifier para a staging table.
| Parâmetro | description |
|---|---|
| body | Json com a lista de IDs que deverão ser eliminados. Um exemplo deste parâmetro é: [{"issuer": {"cod-issente": "33"}}, {"issente": {"cod-emitente": "44"}}] |
| connectorId | O código do conector que a staging table acima pertence. |
| propagateCleanup | Parâmetro que indica se a eliminação dos registros devem ser propagados para o Golden Record e registros rejeitados, desta forma eliminando completamente este registro da Carol. |
| table | O nome da staging table que está sendo eliminado os registros. |
Desta forma que processos externos podem efetuar a eliminação de registros na Carol.