Fornecedores (suppliers)

O recurso suppliers expõe os fornecedores cadastrados na sua conta: razão social, nome fantasia, documento, contatos, endereço e chaves Pix. É um recurso de leitura e escrita, e cada fornecedor é um objeto plano, sem sub-recursos.

Acesso


Módulo	`fornecedores`
Escopos	`suppliers:read` para leitura, `suppliers:write` para escrita
Operações	leitura e escrita

Sem o módulo no contrato, a resposta é 403 module_not_enabled. Sem o escopo na chave, é 403 insufficient_scope. suppliers:write concede também a leitura.

Endpoints

Método	Endpoint	Escopo	Descrição
`GET`	`/v1/suppliers`	`suppliers:read`	Lista fornecedores, com paginação por cursor
`GET`	`/v1/suppliers/{id}`	`suppliers:read`	Busca um fornecedor pelo `id`
`POST`	`/v1/suppliers`	`suppliers:write`	Cria um fornecedor e responde `201`
`PATCH`	`/v1/suppliers/{id}`	`suppliers:write`	Atualização parcial: envie só os campos que mudam
`DELETE`	`/v1/suppliers/{id}`	`suppliers:write`	Desativa o fornecedor e responde `204`

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do fornecedor
`name`	`string \| null`	Nome de exibição, como aparece no app
`legal_name`	`string \| null`	Razão social
`trade_name`	`string \| null`	Nome fantasia
`document_number`	`string \| null`	CPF ou CNPJ
`email`	`string \| null`	E-mail de contato
`phone`	`string \| null`	Telefone principal
`phone1`	`string \| null`	Telefone adicional
`phone2`	`string \| null`	Telefone adicional
`phone3`	`string \| null`	Telefone adicional
`rg`	`string \| null`	RG, para fornecedor pessoa física
`birth_date`	`date (YYYY-MM-DD) \| null`	Data de nascimento, para pessoa física
`is_employee`	`boolean \| null`	Indica se o fornecedor também é colaborador
`code`	`string \| null`	Código interno de referência
`is_active`	`boolean \| null`	`false` quando o fornecedor foi desativado
`address_street`	`string \| null`	Logradouro
`address_number`	`string \| null`	Número
`address_neighborhood`	`string \| null`	Bairro
`address_city`	`string \| null`	Cidade
`address_state`	`string \| null`	UF
`address_country`	`string \| null`	País
`address_zip_code`	`string \| null`	CEP
`pix_keys`	`array<object> \| null`	Chaves Pix do fornecedor
`created_at`	`timestamp`	Data de criação, em ISO 8601
`updated_at`	`timestamp \| null`	Última atualização, em ISO 8601

No POST, todos os campos são opcionais com uma exceção: pelo menos um entre name, legal_name e trade_name é obrigatório. Sem nenhum deles a resposta é 422 validation. O is_active não é aceito no corpo da requisição; o servidor o define como true na criação. No PATCH, envie apenas os campos que quer alterar.

Nos GET, o parâmetro fields devolve campos parciais: ?fields=id,name,document_number,email.

Filtros e ordenação

A sintaxe do filtro é filter[campo][operador]=valor, com os operadores eq, neq, gt, gte, lt, lte, in, nin, ilike e is_null. Os detalhes estão em Paginação, filtros e ordenação.

Campo	Uso típico	Exemplo
`name`	Busca por nome, com `ilike` e `%`	`filter[name][ilike]=%distribuidora%`
`legal_name`	Busca por razão social	`filter[legal_name][ilike]=%ltda%`
`trade_name`	Busca por nome fantasia	`filter[trade_name][ilike]=%beleza%`
`document_number`	Consulta por CPF ou CNPJ	`filter[document_number][eq]=12345678000190`
`email`	Consulta por e-mail	`filter[email][eq]=contato@fornecedor.com.br`
`is_active`	Só os ativos	`filter[is_active][eq]=true`
`is_employee`	Fornecedores que também são colaboradores	`filter[is_employee][eq]=true`
`address_city`	Por cidade	`filter[address_city][ilike]=curitiba`
`address_state`	Por UF	`filter[address_state][eq]=PR`
`created_at`	Por período	`filter[created_at][gte]=2026-01-01`

A ordenação padrão é -created_at, do mais recente para o mais antigo. Os campos aceitos em sort são created_at, updated_at e name.

Exemplos

Os exemplos abaixo supõem as duas variáveis de ambiente do Início rápido:

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

Listar

curl -G "$LIGGA_BASE/v1/suppliers" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "limit=2" \
  --data-urlencode "filter[is_active][eq]=true" \
  --data-urlencode "filter[address_state][eq]=PR" \
  --data-urlencode "sort=-created_at"

{
  "data": [
    {
      "id": "3f8a2b1c-7d4e-4f5a-9b6c-1d2e3f4a5b6c",
      "name": "Beleza Pura Distribuidora",
      "legal_name": "Beleza Pura Distribuidora de Cosméticos LTDA",
      "trade_name": "Beleza Pura",
      "document_number": "12345678000190",
      "email": "compras@belezapura.com.br",
      "phone": "+55 41 3333-4444",
      "phone1": "+55 41 99999-1234",
      "phone2": null,
      "phone3": null,
      "rg": null,
      "birth_date": null,
      "is_employee": false,
      "code": "FORN-001",
      "is_active": true,
      "address_street": "Rua das Flores",
      "address_number": "1500",
      "address_neighborhood": "Centro",
      "address_city": "Curitiba",
      "address_state": "PR",
      "address_country": "Brasil",
      "address_zip_code": "80020-000",
      "pix_keys": [
        { "type": "cnpj", "key": "12345678000190" }
      ],
      "created_at": "2026-06-10T14:22:05.000Z",
      "updated_at": "2026-07-01T09:10:44.000Z"
    },
    {
      "id": "9c1d5e7f-2a3b-4c8d-b0e1-6f7a8b9c0d1e",
      "name": "João Marceneiro",
      "legal_name": null,
      "trade_name": null,
      "document_number": "12345678909",
      "email": null,
      "phone": "+55 41 98888-7777",
      "phone1": null,
      "phone2": null,
      "phone3": null,
      "rg": "1.234.567-8",
      "birth_date": "1985-03-22",
      "is_employee": false,
      "code": null,
      "is_active": true,
      "address_street": null,
      "address_number": null,
      "address_neighborhood": null,
      "address_city": "São José dos Pinhais",
      "address_state": "PR",
      "address_country": "Brasil",
      "address_zip_code": null,
      "pix_keys": [
        { "type": "phone", "key": "+5541988887777" }
      ],
      "created_at": "2026-05-02T11:00:00.000Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjljMWQ1ZTdmLi4uIiwidiI6IjIwMjYtMDUtMDJUMTE6MDA6MDBaIn0",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

O cursor da próxima página está em pagination.next_cursor. Repasse-o em ?cursor= enquanto has_more for true.

Buscar por id

curl "$LIGGA_BASE/v1/suppliers/3f8a2b1c-7d4e-4f5a-9b6c-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

A resposta traz o mesmo objeto de fornecedor da listagem, dentro do envelope de item: { "data": { … }, "meta": { "request_id": "req_…" } }.

Criar

POST é uma operação de escrita. Envie o cabeçalho Idempotency-Key para poder fazer uma nova tentativa sem duplicar o cadastro.

curl -X POST "$LIGGA_BASE/v1/suppliers" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beleza Pura Distribuidora",
    "legal_name": "Beleza Pura Distribuidora de Cosméticos LTDA",
    "trade_name": "Beleza Pura",
    "document_number": "12345678000190",
    "email": "compras@belezapura.com.br",
    "phone": "+55 41 3333-4444",
    "code": "FORN-001",
    "address_city": "Curitiba",
    "address_state": "PR",
    "address_zip_code": "80020-000",
    "pix_keys": [{ "type": "cnpj", "key": "12345678000190" }]
  }'

A resposta é 201 Created com o objeto completo, já com o is_active: true definido pelo servidor:

{
  "data": {
    "id": "3f8a2b1c-7d4e-4f5a-9b6c-1d2e3f4a5b6c",
    "name": "Beleza Pura Distribuidora",
    "legal_name": "Beleza Pura Distribuidora de Cosméticos LTDA",
    "trade_name": "Beleza Pura",
    "document_number": "12345678000190",
    "email": "compras@belezapura.com.br",
    "phone": "+55 41 3333-4444",
    "phone1": null,
    "phone2": null,
    "phone3": null,
    "rg": null,
    "birth_date": null,
    "is_employee": null,
    "code": "FORN-001",
    "is_active": true,
    "address_street": null,
    "address_number": null,
    "address_neighborhood": null,
    "address_city": "Curitiba",
    "address_state": "PR",
    "address_country": null,
    "address_zip_code": "80020-000",
    "pix_keys": [
      { "type": "cnpj", "key": "12345678000190" }
    ],
    "created_at": "2026-07-10T15:30:00.000Z",
    "updated_at": null
  },
  "meta": { "request_id": "req_01JZY0A1B2C3D4E5F6G7H8J9K0" }
}

Atualizar

O PATCH é parcial: os campos que você não enviar continuam como estão.

curl -X PATCH "$LIGGA_BASE/v1/suppliers/3f8a2b1c-7d4e-4f5a-9b6c-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "financeiro@belezapura.com.br",
    "phone1": "+55 41 97777-0000"
  }'

A resposta é 200 OK com o fornecedor já atualizado, no envelope de item.

Desativar

curl -X DELETE "$LIGGA_BASE/v1/suppliers/3f8a2b1c-7d4e-4f5a-9b6c-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

A resposta é 204 No Content, sem corpo. O fornecedor passa a ter is_active: false.

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
401	`token_revoked`	A chave foi revogada
401	`token_expired`	A chave passou da data de expiração
403	`module_not_enabled`	Módulo `fornecedores` fora do contrato
403	`insufficient_scope`	Chave sem `suppliers:read` na leitura ou `suppliers:write` na escrita
404	`not_found`	`id` inexistente ou pertencente a outra conta
409	`idempotency_conflict`	Mesma `Idempotency-Key` reaproveitada com corpo diferente
422	`validation`	`POST` sem nenhum de `name`, `legal_name` e `trade_name`; `birth_date` fora do formato `YYYY-MM-DD`; e-mail inválido; filtro, operador ou cursor não aceito
429	`rate-limit-exceeded`	Limite de requisições do plano excedido

O corpo do erro traz type, title, status e request_id. O formato completo está em Erros.

Veja também

Despesas (expenses) — o supplier_id que aponta para cá
Paginação, filtros e ordenação — cursor, filter, sort e fields
Idempotência — como repetir uma escrita com segurança
Módulos e escopos — o que fornecedores habilita