Como integrar com o CBA via API – Tamago

Neste artigo, aprenderemos como integrar com o CBA via API.

Encontrando a Documentação da API

1. Acesse o console do CBA em https://cba-admin.tamago.app

Clique no botão “Documentação” e “Documentação da API“:

Você terá acesso à documentação da TCBA API:

Gerando a chave para acessar a API

Para conseguir publicar dados na API é necessário ter um usuário e uma chave de acesso para a API. Um novo usuário pode ser criado no console ou uma nova chave gerada no console CBA:

Clique na opção “Usuários“:

A tela de usuários será apresentada. Clique em “Novo Usuário” para criar um novo usuário para a ferramenta.

Defina as seguintes informações:

Atributo	Descrição
Partner Code	O Partner Code é o código que identifica a sua Organização no CBA. Este atributo não pode ser alterado, pois é definido no setup.
User	Defina o e-mail do usuário que será o responsável pela integração.
Role	Defina uma Role de Acesso para o usuário. Existem três Roles: Reader: é uma role geralmente para os usuários que vão acessar os relatórios do CBA. Eles não são capazes de fazer mudanças e possuem apenas acesso de leitura; Editor: é uma role que permite a ingestão de dados no CBA. Para poder integrar os dados é necessário atribuir este acesso; Admin: é uma role de administração, que permite alterar dados, configurações da organização, criar e alterar o acesso dos usuários;
Password	É uma senha de acesso atribuída para a geração da chave de API. Ela deve ser definida uma única vez, na criação do usuário ou quando for necessário renovar ou criar uma nova chave. Cada usuário pode ter uma única chave, portanto para que uma nova chave de API seja criada, é necessário revogar a chave anterior.
Key Expiration Date	Indique a data de validade da chave de API. Por questões de segurança, recomendamos que essa chave tenha a validade de 90 dias no máximo.

Clique no botão “Gravar” para criar o usuário. Em seguida, acesse no painel lateral do usuário o atributo “Api Key“, copie e guarde para a próxima etapa.

Não divulgue essa senha, pois ela dá acesso ao ambiente. A chave mostrada neste exemplo é de um ambiente de testes e já foi revogada.

Realizando a integração de dados

Realize a integração de dados de acordo com a documentação. Abaixo mostramos como a API REST é invocada para realizar a ingestão de uma nova venda. A API Key é fornecida como um header x-api-key para a API, que saberá quem é o usuário que está requisitando a ingestão do dado, a organização e as outras informações.

Exemplo de integração com o cURL:

curl --location 'https://cba.tamago.app:443/v1/sales' \
--header 'x-api-key: b1012d1d596993956c41e1b7011066d3760edf7de76f2b5dbc9900a5fa4e461a' \
--header 'Content-Type: application/json' \
--data '[
    {
        "partner_code": "TMG001",
        "version": "V00",
        "order_id": "O2564035339318",
        "customer_id": "C006753",
        "order_date": "2018-04-17",
        "product_id": "P007166",
        "sales": 67.58,
        "quantity": 1,
        "profit": 11.22,
        "source_code": "TST"
    }
]'

Exemplo de integração com Python (Requests):

import requests
import json

url = "https://cba.tamago.app:443/v1/sales"

payload = json.dumps([
  {
    "partner_code": "TMG001",
    "version": "V00",
    "order_id": "O2564035339318",
    "customer_id": "C006753",
    "order_date": "2018-04-17",
    "product_id": "P007166",
    "sales": 67.58,
    "quantity": 1,
    "profit": 11.22,
    "source_code": "TST"
  }
])
headers = {
  'x-api-key': 'b1012d1d596993956c41e1b7011066d3760edf7de76f2b5dbc9900a5fa4e461a',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Exemplo de integração com NodeJs e Axios:

const axios = require('axios');
let data = JSON.stringify([
  {
    "partner_code": "TMG001",
    "version": "V00",
    "order_id": "O2564035339318",
    "customer_id": "C006753",
    "order_date": "2018-04-17",
    "product_id": "P007166",
    "sales": 67.58,
    "quantity": 1,
    "profit": 11.22,
    "source_code": "TST"
  }
]);

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://cba.tamago.app:443/v1/sales',
  headers: { 
    'x-api-key': 'b1012d1d596993956c41e1b7011066d3760edf7de76f2b5dbc9900a5fa4e461a', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

A Tamago oferece também uma Coleção do Postman com payloads de exemplo, que você pode usar para entender testar as chamadas.

Relativo a