Este documento contém a documentação completa da API, incluindo métodos de autenticação, headers necessários, endpoints disponíveis, formatos de payload e exemplos práticos de uso.
Índice
Autenticação
Para utilizar a API, é necessário seguir um processo de autenticação em duas etapas:
1. Obtenção da API Key
Antes de fazer requisições à API, você precisa obter uma API Key seguindo estes passos:
- Acesse o menu Sys → Integrações → Robos no sistema
- Adicione um novo robô vinculado a um usuário válido
- Pode ser necessário criar um usuário no sistema previamente
- Certifique-se de adicionar as permissões necessárias a este usuário
- Após a criação do robô, você terá acesso à API Key associada a ele
2. Obtenção do Token de Autenticação
Com a API Key em mãos, você deve obter um token de autenticação:
POST /puca-user/system_user/login
Body:
{
"api_key": "sua_api_key_aqui"
}
Resposta:
A resposta conterá um token de autenticação que deve ser utilizado em todas as requisições subsequentes.
3. Utilização do Token
Para todas as requisições à API, inclua o token obtido no header Authorization:
Authorization: seu_token_aqui
Importante: O token deve ser incluído em todas as requisições subsequentes para autenticar o acesso à API.
Headers
Para realizar requisições à API, os seguintes headers são obrigatórios:
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Authorization |
{token} |
Token de autenticação obtido através do endpoint de login. |
Content-Type |
application/json |
Define o formato do conteúdo enviado nas requisições como JSON. |
Exemplo de Headers
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Endpoints
Esta seção descreve os endpoints disponíveis na API, seus métodos HTTP suportados e exemplos de uso.
Endpoints Disponíveis
A API possui diversos endpoints que variam de acordo com a tabela do sistema. Abaixo está documentado o endpoint de pessoa/empresa como exemplo:
Endpoint: puca-crm-api/person
Este endpoint permite gerenciar dados de pessoas e empresas no sistema.
Métodos Suportados
| Método | Descrição |
|---|---|
| GET | Consultar pessoas/empresas |
| POST | Criar ou atualizar pessoas/empresas |
| DELETE | Remover pessoas/empresas |
GET
O método GET pode ser utilizado de duas maneiras:
1. Consulta com Query Puca
GET /puca-crm-api/person
Para este método, é necessário enviar uma query Puca no corpo da requisição, conforme definido na documentação de queries.
Exemplo de consulta pelos campos ‘name’, ‘cpf_cnpj’ e ‘puca_key’:
{
"from": "puca_crm_api_person",
"fields": [
"puca_key",
"name",
"cpf_cnpj"
]
}
Exemplo com filtro:
{
"from": "puca_crm_api_person",
"fields": [
"puca_key",
"name",
"cpf_cnpj"
],
"args": {
"natureza": "J"
},
"where": {
"and": [
{
"v1": "natureza",
"operator": "equals",
"v2": "$natureza"
}
]
}
}
2. Consulta por ID
GET /puca-crm-api/person/:id
Para este método, é necessário fornecer o ID (uuid) do registro e o parâmetro fields na query string.
Parâmetros:
:id- UUID do registro no sistemafields- Campos a serem retornados (separados por vírgula)
Exemplo:
GET /puca-crm-api/person/550e8400-e29b-41d4-a716-446655440000?fields=name,cpf_cnpj,puca_key
POST
O método POST pode ser utilizado de duas maneiras:
1. Criação de novo registro
POST /puca-crm-api/person
Corpo da requisição:
{
"name": "Nome da Pessoa ou Empresa",
"cpf_cnpj": "12345678901",
"contact_email": "[email protected]",
...
}
2. Atualização de registro existente (Upinsert)
POST /puca-crm-api/person
Corpo da requisição:
{
"puca_pid": "550e8400-e29b-41d4-a716-446655440000",
"name": "Nome Atualizado",
"cpf_cnpj": "12345678901",
...
}
Nota: As colunas disponíveis podem ser encontradas no path:
https://[[host]]/puca-base-front/3.4.5/#/module/0=puca-crud-front%2Flist%2Fuser_table_dictionary&1=puca-crud-front%2Fdictionary%2F[[nome da tabela]]
DELETE
DELETE /puca-crm-api/person/:id
Parâmetros:
:id- UUID do registro a ser removido
Permissões
Todas as APIs só executarão ações que o usuário vinculado ao robô tenha acesso. Certifique-se de que o usuário associado à API Key possua as permissões necessárias para as operações desejadas.
Validações e Restrições
- As operações estão sujeitas às permissões do usuário vinculado ao robô
- Os campos obrigatórios devem ser preenchidos conforme o dicionário de dados da tabela
- O formato e as validações específicas de cada campo (como formato de CPF/CNPJ, email, etc.) são definidos no dicionário de dados da tabela
Exemplos de Uso
Esta seção fornece exemplos práticos de como utilizar a API com diferentes ferramentas e linguagens de programação.
Autenticação
Todos os exemplos abaixo assumem que você já possui uma API Key obtida através do menu Sys → Integrações → Robos no sistema.
Obtenção do Token de Autenticação
cURL
curl -X POST \
https://[[host]]/puca-user/system_user/login \
-H 'Content-Type: application/json' \
-d '{
"api_key": "sua_api_key_aqui"
}'
JavaScript (Fetch API)
const obterToken = async () => {
const response = await fetch('https://[[host]]/puca-user/system_user/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
api_key: 'sua_api_key_aqui'
})
});
const data = await response.json();
const token = data.token; // Ajuste conforme a estrutura real da resposta
return token;
};
Exemplos de Operações com o Endpoint de Pessoa/Empresa
GET - Consulta com Query Puca
JavaScript (Fetch API)
const consultarPessoas = async (token) => {
const response = await fetch('https://[[host]]/puca-crm-api/person', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
from: 'puca_crm_api_person',
fields: [
'puca_key',
'name',
'cpf_cnpj'
],
"args": {
"natureza": "J"
},
where: {
and: [
{
v1: 'natureza',
operator: 'equals',
v2: '$natureza'
}
]
}
})
});
const data = await response.json();
return data;
};
GET - Consulta por ID
cURL
curl -X GET \
'https://[[host]]/puca-crm-api/person/550e8400-e29b-41d4-a716-446655440000?fields=name,cpf_cnpj,puca_key' \
-H 'Authorization: seu_token_aqui' \
-H 'Content-Type: application/json'
JavaScript (Fetch API)
const consultarPessoaPorId = async (token, id) => {
const response = await fetch(`https://[[host]]/puca-crm-api/person/${id}?fields=name,cpf_cnpj,puca_key`, {
method: 'GET',
headers: {
'Authorization': `${token}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
return data;
};
POST - Criação de Novo Registro
cURL
curl -X POST \
https://[[host]]/puca-crm-api/person \
-H 'Authorization: seu_token_aqui' \
-H 'Content-Type: application/json' \
-d '{
"name": "Nome da Pessoa ou Empresa",
"cpf_cnpj": "12345678901",
"contact_email": "[email protected]"
}'
JavaScript (Fetch API)
const criarPessoa = async (token, dadosPessoa) => {
const response = await fetch('https://[[host]]/puca-crm-api/person', {
method: 'POST',
headers: {
'Authorization': `${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(dadosPessoa)
});
const data = await response.json();
return data;
};
// Exemplo de uso
const dadosPessoa = {
name: 'Nome da Pessoa ou Empresa',
cpf_cnpj: '12345678901',
contact_email: '[email protected]'
};
criarPessoa(token, dadosPessoa)
.then(resultado => console.log(resultado))
.catch(erro => console.error(erro));
POST - Atualização de Registro Existente (Upinsert)
cURL
curl -X POST \
https://[[host]]/puca-crm-api/person \
-H 'Authorization: seu_token_aqui' \
-H 'Content-Type: application/json' \
-d '{
"puca_pid": "550e8400-e29b-41d4-a716-446655440000",
"name": "Nome Atualizado",
"cpf_cnpj": "12345678901",
"contact_email": "[email protected]"
}'
JavaScript (Fetch API)
const atualizarPessoa = async (token, dadosPessoa) => {
const response = await fetch('https://[[host]]/puca-crm-api/person', {
method: 'POST',
headers: {
'Authorization': `${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(dadosPessoa)
});
const data = await response.json();
return data;
};
// Exemplo de uso
const dadosPessoa = {
puca_pid: '550e8400-e29b-41d4-a716-446655440000',
name: 'Nome Atualizado',
cpf_cnpj: '12345678901',
contact_email: '[email protected]'
};
atualizarPessoa(token, dadosPessoa)
.then(resultado => console.log(resultado))
.catch(erro => console.error(erro));
DELETE - Remoção de Registro
cURL
curl -X DELETE \
https://[[host]]/puca-crm-api/person/550e8400-e29b-41d4-a716-446655440000 \
-H 'Authorization: seu_token_aqui' \
-H 'Content-Type: application/json'
JavaScript (Fetch API)
const removerPessoa = async (token, id) => {
const response = await fetch(`https://[[host]]/puca-crm-api/person/${id}`, {
method: 'DELETE',
headers: {
'Authorization': `${token}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
return data;
};
// Exemplo de uso
removerPessoa(token, '550e8400-e29b-41d4-a716-446655440000')
.then(resultado => console.log(resultado))
.catch(erro => console.error(erro));
Collection Postman
{
"info": {
"_postman_id": "b403dbd9-9cb5-47aa-8abd-2564efd323fa",
"name": "Puca API Exemplo",
"description": "Coleção de exemplo para a API Puca, baseada na documentação gerada. Inclui autenticação e operações para o endpoint de Pessoa/Empresa.",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_exporter_id": "40102894"
},
"item": [
{
"name": "Autenticação",
"item": [
{
"name": "Obter Token de Autenticação",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test(\"Status code is 200\", function () {",
" pm.response.to.have.status(200);",
"});",
"",
"// Extrair o token da resposta e definir a variável da coleção",
"try {",
" var jsonData = pm.response.json();",
" if (jsonData && jsonData.token) { // Ajuste 'jsonData.token' conforme a estrutura real da resposta",
" pm.collectionVariables.set(\"auth_token\", jsonData.token);",
" console.log(\"Token de autenticação salvo na variável 'auth_token'\");",
" } else {",
" console.error(\"Token não encontrado na resposta. Verifique a estrutura da resposta JSON.\");",
" }",
"} catch (e) {",
" console.error(\"Erro ao processar a resposta JSON: \", e);",
"}"
],
"type": "text/javascript",
"packages": {}
}
},
{
"listen": "prerequest",
"script": {
"exec": [
""
],
"type": "text/javascript",
"packages": {}
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"api_key\": \"{{api_key}}\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/puca-user/system_user/login",
"host": [
"{{base_url}}"
],
"path": [
"puca-user",
"system_user",
"login"
]
},
"description": "Obtém o token de autenticação usando a API Key. O token é salvo automaticamente na variável de coleção 'auth_token'."
},
"response": []
}
]
},
{
"name": "Pessoa/Empresa (puca-crm-api/person)",
"item": [
{
"name": "GET - Consultar Pessoas (Query Puca com Filtro)",
"event": [
{
"listen": "prerequest",
"script": {
"exec": [
"const obj = { ",
" args: {",
" puca_key: 8",
" },",
" where: {",
" v1: 'puca_key',",
" v2: '$puca_key',",
" operator: 'equals'",
" }",
" };",
"pm.variables.set('args', encodeURIComponent(JSON.stringify(obj.args)));",
"pm.variables.set('where', encodeURIComponent(JSON.stringify(obj.where)));"
],
"type": "text/javascript",
"packages": {}
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "{{auth_token}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/puca-crm-api/person?fields[0]=puca_pid&fields[1]=name&args={{args}}&where={{where}}",
"host": [
"{{base_url}}"
],
"path": [
"puca-crm-api",
"person"
],
"query": [
{
"key": "fields[0]",
"value": "puca_pid"
},
{
"key": "fields[1]",
"value": "name"
},
{
"key": "args",
"value": "{{args}}"
},
{
"key": "where",
"value": "{{where}}"
}
]
},
"description": "Consulta pessoas/empresas usando Query Puca no corpo da requisição, com filtro para natureza = 'J'."
},
"response": []
},
{
"name": "GET - Consultar Pessoa por ID",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "{{auth_token}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/puca-crm-api/person/{{person_id}}?fields[0]=cpf_cnpj",
"host": [
"{{base_url}}"
],
"path": [
"puca-crm-api",
"person",
"{{person_id}}"
],
"query": [
{
"key": "fields[0]",
"value": "cpf_cnpj"
}
]
},
"description": "Consulta uma pessoa/empresa específica pelo seu ID (UUID). O ID deve ser definido na variável 'person_id'."
},
"response": []
},
{
"name": "POST - Criar Pessoa/Empresa",
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "{{auth_token}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Nome Exemplo LTDA\",\n \"cpf_cnpj\": \"12345678000199\",\n \"natureza\": \"J\" \n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/puca-crm-api/person",
"host": [
"{{base_url}}"
],
"path": [
"puca-crm-api",
"person"
]
},
"description": "Cria um novo registro de pessoa/empresa."
},
"response": []
},
{
"name": "POST - Atualizar Pessoa/Empresa (Upinsert)",
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "{{auth_token}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"puca_pid\": \"{{person_id}}\",\n \"name\": \"Nome Exemplo Atualizado LTDA\",\n \"cpf_cnpj\": \"12345678000199\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/puca-crm-api/person",
"host": [
"{{base_url}}"
],
"path": [
"puca-crm-api",
"person"
]
},
"description": "Atualiza um registro existente de pessoa/empresa utilizando o puca_pid. O ID deve ser definido na variável 'person_id'."
},
"response": []
},
{
"name": "DELETE - Remover Pessoa/Empresa",
"request": {
"method": "DELETE",
"header": [
{
"key": "Authorization",
"value": "Bearer {{auth_token}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/puca-crm-api/person/{{person_id}}",
"host": [
"{{base_url}}"
],
"path": [
"puca-crm-api",
"person",
"{{person_id}}"
]
},
"description": "Remove um registro de pessoa/empresa pelo seu ID (UUID). O ID deve ser definido na variável 'person_id'."
},
"response": []
}
]
}
],
"event": [
{
"listen": "prerequest",
"script": {
"type": "text/javascript",
"exec": [
""
]
}
},
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
""
]
}
}
]
}