cURL

cURL está em qualquer terminal Unix e não exige dependência nenhuma. É a forma mais direta de conferir uma chave, inspecionar o envelope de resposta e reproduzir um problema antes de levá-lo para o código.

Configuração

Duas variáveis de ambiente bastam para todos os exemplos desta página.

export LIGGA_API_KEY='ligga_live_…'
export LIGGA_BASE='https://api.ligga.app/functions/v1/api'

Os exemplos usam jq para ler campos do JSON. Ele não é obrigatório, mas encurta bastante os laços de paginação.

Cuidado

Uma chave ligga_test_ conversa com a mesma base de dados da chave de produção. Escrita em modo teste cria registro real. Veja Modo teste.

Primeira requisição

GET /v1/me descreve a chave que fez a chamada. É a forma recomendada de confirmar que a configuração está correta.

curl "$LIGGA_BASE/v1/me" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "team_id": "bca09e2f-41ab-4417-b84b-f2ff50f991ca",
    "key_name": "Integração ERP",
    "key_prefix": "live",
    "scopes": ["*:read", "sales:write"],
    "plan_code": "pro",
    "modules": ["clientes", "vendas"]
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

Listar com paginação

Uma listagem devolve os itens em data e o estado da paginação em pagination. O cursor da próxima página está em pagination.next_cursor, e pagination.has_more diz se ainda há o que buscar.

curl "$LIGGA_BASE/v1/customers?limit=20&filter[full_name][ilike]=Ana%25" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": [
    { "id": "7c4b0a19-2f36-4d1e-9b58-1f0a6c3e5d24", "full_name": "Ana Ribeiro" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjdjNGIwYTE5IiwidiI6IjIwMjYtMDUtMThUMTI6MzQ6NTZaIn0",
    "has_more": true,
    "limit": 20
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

O cursor é opaco: você o copia da resposta anterior, nunca o constrói. Para a próxima página, repita a requisição acrescentando &cursor=<next_cursor>.

Para percorrer todas as páginas, leia o cursor a cada volta e pare quando ele vier null:

listar-clientes.sh

#!/usr/bin/env bash
set -euo pipefail

cursor=''
while :; do
  url="$LIGGA_BASE/v1/customers?limit=100"
  [ -n "$cursor" ] && url="$url&cursor=$cursor"

  page=$(curl -sS "$url" -H "Authorization: Bearer $LIGGA_API_KEY")
  echo "$page" | jq -r '.data[] | "\(.id)\t\(.full_name)"'

  cursor=$(echo "$page" | jq -r '.pagination.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Cuidado

O cursor está em pagination.next_cursor, não em meta. Um laço que lê meta.next_cursor recebe null na primeira volta e nunca avança para a segunda página.

Escrita idempotente

Toda escrita aceita o cabeçalho Idempotency-Key. Se a requisição se perder no caminho, repita a chamada com a mesma chave: a API devolve a resposta original em vez de criar um segundo registro.

Criar cliente

curl -X POST "$LIGGA_BASE/v1/customers" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Ana Ribeiro",
    "email": "ana@example.com",
    "phone": "+5511999990000"
  }'

full_name é obrigatório e pelo menos um entre email e phone precisa vir preenchido.

Ao escrever um script com nova tentativa, gere a chave antes do primeiro envio e reaproveite o mesmo valor em todas as tentativas:

criar-cliente.sh

#!/usr/bin/env bash
set -euo pipefail

chave=$(uuidgen)

for tentativa in 1 2 3; do
  status=$(curl -sS -o resposta.json -w '%{http_code}' \
    -X POST "$LIGGA_BASE/v1/customers" \
    -H "Authorization: Bearer $LIGGA_API_KEY" \
    -H "Idempotency-Key: $chave" \
    -H "Content-Type: application/json" \
    -d '{"full_name":"Ana Ribeiro","email":"ana@example.com"}')

  if [ "$status" -lt 500 ] && [ "$status" != 429 ]; then
    break
  fi
  sleep $((tentativa * 2))
done

jq . resposta.json

Criar venda com itens

curl -X POST "$LIGGA_BASE/v1/sales" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "7c4b0a19-2f36-4d1e-9b58-1f0a6c3e5d24",
    "transaction_type": "sale",
    "sale_date": "2026-05-18",
    "items": [
      {
        "catalog_type": "product",
        "catalog_item_id": "3d61f8ba-9c04-4a77-8e12-5b7a0d9f2c68",
        "quantity": 2,
        "unit_price": 29.90
      }
    ]
  }'

Atualizar e desativar

PATCH altera só os campos enviados:

curl -X PATCH "$LIGGA_BASE/v1/customers/7c4b0a19-2f36-4d1e-9b58-1f0a6c3e5d24" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Cliente preferencial"}'

DELETE desativa o registro (is_active=false) e responde 204 sem corpo. O histórico continua consultável:

curl -X DELETE "$LIGGA_BASE/v1/customers/7c4b0a19-2f36-4d1e-9b58-1f0a6c3e5d24" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

Tratamento de erros

Respostas de erro vêm como application/problem+json, com type, title, status e request_id sempre presentes, e detail, instance e errors quando fazem sentido.

curl -i "$LIGGA_BASE/v1/customers" \
  -X POST \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "type": "https://api.ligga.app/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "full_name is required",
  "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V"
}

Para extrair os campos que o suporte pede:

curl -sS -X POST "$LIGGA_BASE/v1/customers" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  | jq -r '"\(.status) \(.type)\n\(.detail // .title)\nrequest_id: \(.request_id)"'

O mesmo identificador acompanha a resposta no cabeçalho X-Request-Id, útil quando o corpo não é JSON:

curl -sS -o /dev/null -D - "$LIGGA_BASE/v1/me" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  | grep -i x-request-id

Os códigos mais frequentes:

HTTP	type	O que fazer
401	invalid_token	Confira o cabeçalho Authorization e o valor da chave
403	insufficient_scope	A chave não carrega o escopo do recurso
403	module_not_enabled	O módulo do recurso não está no contrato
409	idempotency_conflict	A mesma Idempotency-Key foi reusada com outro corpo
422	validation	Campo obrigatório ausente ou com tipo errado
429	rate-limit-exceeded	Espere o tempo do cabeçalho Retry-After

Extras

Cabeçalhos de limite

Toda resposta traz o estado do limite de requisições. Para ver só os cabeçalhos:

curl -sS -o /dev/null -D - "$LIGGA_BASE/v1/customers" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  | grep -i x-ratelimit

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1779123456

Depuração

-v mostra a negociação completa, incluindo os cabeçalhos enviados:

curl -v "$LIGGA_BASE/v1/me" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

Veja também

• Início rápido — a primeira chamada, passo a passo
• Paginação, filtros e ordenação — operadores e sort
• Idempotência — o ciclo de vida da Idempotency-Key
• Erros — o catálogo completo de type