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

Cuidado

DELETE não apaga o registro. Ele define is_active=false para preservar o histórico de despesas ligado ao fornecedor. O registro continua aparecendo em GET /v1/suppliers, agora com is_active: false; filtre com filter[is_active][eq]=true para ver apenas os ativos. Repetir o DELETE no mesmo id responde 204 de novo. A API pública não oferece uma operação de reativação.

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.

Subcadastros e vínculos

Os subcadastros usam os mesmos escopos suppliers:read e suppliers:write. Cada coleção permite listar e criar; GET, PATCH e DELETE em /<id> consultam, editam e removem/desativam conforme o recurso.

Coleção	Conteúdo
/v1/suppliers/tags	Tags
/v1/suppliers/custom-fields	Definições de campos personalizados
/v1/suppliers/document-types	Tipos de documento
/v1/suppliers/field-requirements	Obrigatoriedade de campos
/v1/suppliers/{supplier_id}/documents	Documentos

Listagens dos subcadastros usam after (UUID do último item) e limit (1 a 100, padrão 50). Elas não aceitam o cursor opaco dos cadastros principais.

Para substituir os vínculos do cadastro, use PUT /v1/suppliers/{id}/tags com tag_ids e PUT /v1/suppliers/{id}/custom-field-values com custom_field_values. GET nos mesmos caminhos consulta os valores.

Documentos são enviados em JSON com conteúdo base64 (máximo de 5 MiB por arquivo), nos tipos PDF, JPEG, PNG ou texto. O servidor define o caminho de armazenamento e valida a cota do contrato. Para baixar, consulte /{id}/documents/{document_id}/download: a URL assinada vale por cinco minutos. Nunca publique essa URL como endereço permanente. Consulte na Referência o schema completo de upload e os campos de cada recurso.

Alterações compostas de cadastro e vínculos usam transações. Em caso de falha indeterminada, siga Idempotência antes de repetir a escrita.

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