Consultar linhas de um cadastro

Consultar linhas de um cadastro

POST /register/v2/query

Retorna as linhas de um cadastro de forma paginada, permitindo escolher os campos (select), filtrar, ordenar e buscar — tudo através de um único parâmetro filterSchema.

A resposta é paginada por cursor (não por página/offset), o que mantém a performance mesmo em cadastros com centenas de milhares de linhas.

Toda a requisição é escopada pela empresa e pelo usuário do seu token. Você só recebe linhas às quais esse usuário tem acesso.

1. Autenticação e headers

A API usa um JWT no header Authorization: Bearer <token>. Veja como obter e renovar seu token na página de Autenticação.

Toda chamada precisa destes headers:

Header	Valor	Obrigatório
Authorization	Bearer <token>	✅
Content-Type	application/json	✅
Origin	https://app.cange.me	✅

O header Origin: https://app.cange.me é obrigatório em todas as chamadas. A API só aceita origens da allowlist — uma requisição com Origin diferente é bloqueada por CORS.

2. A requisição

POST /register/v2/query
Authorization: Bearer <token>
Content-Type: application/json
Origin: https://app.cange.me

Campo	Tipo	Obrigatório	Descrição
id_register	integer	✅	ID do cadastro.
filterSchema	string (JSON)	—	Select, filtros, ordenação e busca (ver abaixo).
page_size	integer	—	Linhas por página. Padrão 50, máximo 200.
cursor	string	—	Cursor da próxima página (vem em page_info.next_cursor).

Chamada mínima (sem filterSchema) — retorna as primeiras linhas com as colunas de sistema:

curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{ "id_register": 183, "page_size": 20 }'

3. O filterSchema

O filterSchema é uma string JSON com quatro blocos, todos opcionais:

{
  "fieldView":  [ /* quais campos retornar (SELECT) */ ],
  "conditions": [ /* filtros (combinados com E) */ ],
  "orderBy":    [ /* ordenação */ ],
  "searchText": "texto de busca livre"
}

Descobrindo os campos do cadastro

Para montar fieldView, conditions e orderBy você precisa do id_field, do form_id e do type de cada campo. Busque a estrutura do cadastro:

curl "https://api.cange.me/register/v2/?id_register=183" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Origin: https://app.cange.me"

O form.id_form é o form_id; cada item de form.fields[] traz id_field e type.

fieldView — escolher os campos (SELECT)

Cada item precisa dos três identificadores:

{ "id_field": 9803, "form_id": 2957, "type": "TEXT_SHORT_FIELD" }

Se você omitir form_id (ou type), o campo é silenciosamente ignorado e não volta na resposta. Se fieldView estiver vazio, a resposta traz apenas as colunas de sistema (sem os campos do cadastro).

Campos de sistema usam IDs negativos: -1 = data de criação, -2 = usuário criador, -3 = ID da linha.

conditions — filtrar

Filtros são combinados com E. Cada condição:

{
  "selectedField": { "id_field": 9803, "form_id": 2957, "type": "TEXT_SHORT_FIELD" },
  "selectedComparator": "Contém",
  "value": "construtora"
}

orderBy — ordenar

{
  "selectedField": { "id_field": 9803, "type": "TEXT_SHORT_FIELD" },
  "selectedOrder": "A → Z"
}

Direções por tipo: texto "A → Z" / "Z → A"; número "1 → 9" / "9 → 1"; booleano "Verdadeiro → Falso" / "Falso → Verdadeiro"; datas do mais novo/antigo.

4. Comparadores

selectedComparator aceita tanto o rótulo em português quanto o operador SQL equivalente:

Rótulo	SQL	Observação
Igual a	=
Não é igual a	!=
Contém	LIKE	busca parcial
Não contém	NOT LIKE
Semelhante a	fulltext	busca por similaridade
Maior que / Menor que	> / <
Igual a ou maior que / ... menor que	>= / <=
Está em branco / Não está em branco	IS NULL / IS NOT NULL	ignora value
É uma das / Não é uma das	IN / NOT IN	value separado por vírgula
Antes de / Depois de	< / >	datas

5. Exemplos

Selecionar campos específicos:

curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{
    "id_register": 183,
    "page_size": 20,
    "filterSchema": "{\"fieldView\":[{\"id_field\":-3},{\"id_field\":9803,\"form_id\":2957,\"type\":\"TEXT_SHORT_FIELD\"},{\"id_field\":36776,\"form_id\":2957,\"type\":\"COMBO_BOX_FIELD\"}]}"
  }'

Filtrar + ordenar:

curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{
    "id_register": 183,
    "filterSchema": "{\"conditions\":[{\"selectedField\":{\"id_field\":9803,\"form_id\":2957,\"type\":\"TEXT_SHORT_FIELD\"},\"selectedComparator\":\"Contém\",\"value\":\"construtora\"}],\"orderBy\":[{\"selectedField\":{\"id_field\":9803,\"type\":\"TEXT_SHORT_FIELD\"},\"selectedOrder\":\"A → Z\"}]}"
  }'

Próxima página (cursor):

curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{ "id_register": 183, "page_size": 20, "cursor": "eyJzb3J0X3Zh..." }'

6. Formato da resposta

{
  "items": [
    {
      "form_answer.id_form_answer": 6507,
      "form_answer.register_id": 183,
      "form_answer.dt_created": "2023-04-06T22:16:01.000Z",
      "form_answer.user_id_creator": 76,
      "field:9803": {
        "value": "Empresa Exemplo LTDA",
        "display_value": "Empresa Exemplo LTDA",
        "value_number": null,
        "value_date": null,
        "value_bool": null,
        "related_id": null
      }
    }
  ],
  "page_info": { "next_cursor": "eyJzb3J0X3Zh...", "has_more": true },
  "execution_stats": { "plan": "large", "cached": false, "duration_ms": 24, "total_count": 316 }
}

Cada linha traz as colunas de sistema (form_answer.*) e um objeto field:<id_field> por campo selecionado:

• value — valor bruto; display_value — valor exibível (rótulo de combo, etc.).

• value_number / value_date / value_bool — valor tipado quando aplicável.

• related_id — para campos que referenciam outro cadastro/fluxo.

Continue paginando enquanto page_info.has_more for true, passando page_info.next_cursor na próxima chamada.