Documentação da API padrão do Puca

General
2

Existe mais um endpoint que pode ser útil ou simplificar as consultas:

Endpoint: POST /find

Este endpoint permite realizar consultas complexas utilizando a Query Puca enviada diretamente no corpo da requisição, utilizando o método POST. Isso pode facilitar o envio de queries mais longas ou complexas que poderiam exceder limites de URL se enviadas via GET.

Requisição

POST /find

Contexto: Este endpoint deve ser utilizado no contexto da entidade desejada. Por exemplo, para buscar pessoas/empresas, o path completo seria puca-crm-api/person/find.

Headers Obrigatórios:

Header Valor Descrição
Authorization Bearer {token} Token de autenticação obtido através do endpoint de login.
Content-Type application/json Define o formato do conteúdo enviado na requisição como JSON.

Corpo da Requisição (Payload):

O corpo da requisição deve conter um objeto JSON representando a Query Puca, conforme a estrutura definida na documentação de queries.

Exemplo de Payload (buscando pessoas/empresas com natureza = ‘J’):

{
  "from": "puca_crm_api_person",
  "fields": [
    "puca_key",
    "name",
    "cpf_cnpj"
  ],
  "where": {
    "and": [
      {
        "v1": "natureza",
        "operator": "equals",
        "v2": "J"
      }
    ]
  }
}

Resposta

Sucesso (200 OK):
A resposta conterá um array de objetos JSON, onde cada objeto representa um registro encontrado que corresponde aos critérios da query.

[
  {
    "puca_key": 123,
    "name": "Empresa Exemplo 1",
    "cpf_cnpj": "11222333000144"
  },
  {
    "puca_key": 456,
    "name": "Empresa Exemplo 2",
    "cpf_cnpj": "44555666000177"
  }
]

Erro:
Em caso de erro (query inválida, token inválido, etc.), a API retornará um status de erro apropriado (como 400, 401, 500) com uma mensagem descritiva no corpo da resposta.

Permissões

A consulta retornará apenas os dados aos quais o usuário vinculado ao robô (e ao token) tem permissão de acesso.

Exemplos de Uso

cURL

curl -X POST \
  https://[[host]]/puca-crm-api/person/find \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "puca_crm_api_person",
    "fields": [
      "puca_key",
      "name",
      "cpf_cnpj"
    ],
    "where": {
      "and": [
        {
          "v1": "natureza",
          "operator": "equals",
          "v2": "J"
        }
      ]
    }
  }'

JavaScript (Fetch API)

const buscarComPost = async (token, queryPuca) => {
  const response = await fetch('https://[[host]]/puca-crm-api/person/find', { // Ajuste o path conforme a entidade
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(queryPuca)
  });
  
  const data = await response.json();
  return data;
};

// Exemplo de uso
const query = {
  from: 'puca_crm_api_person',
  fields: [
    'puca_key',
    'name',
    'cpf_cnpj'
  ],
  where: {
    and: [
      {
        v1: 'natureza',
        operator: 'equals',
        v2: 'J'
      }
    ]
  }
};

buscarComPost(token, query)
  .then(resultado => console.log(resultado))
  .catch(erro => console.error(erro));

Postman

  1. Crie uma nova requisição POST
  2. URL: {{base_url}}/puca-crm-api/person/find (Ajuste o path conforme a entidade)
  3. Na aba Headers, adicione:
    • Key: Authorization
    • Value: Bearer {{auth_token}}
    • Key: Content-Type
    • Value: application/json
  4. Na aba Body, selecione “raw” e “JSON”, e insira:
    {
  "from": "puca_crm_api_person",
  "fields": [
    "puca_key",
    "name",
    "cpf_cnpj"
  ],
  "where": {
    "and": [
      {
        "v1": "natureza",
        "operator": "equals",
        "v2": "J"
      }
    ]
  }
}
  5. Clique em “Send”