Pacotes

A API v1 de pacotes é uma interface de consulta dos kits e das respectivas composições do produtor autenticado.

Atenção

Somente leitura. A versão atual expõe apenas os dois GET abaixo — não há rota para criar, atualizar ou excluir pacotes. Faça essas operações pelo painel do Paylog. POST, PUT, PATCH e DELETE em /api/v1/pacotes ou /api/v1/pacotes/{id} retornam sempre 405 Method Not Allowed, antes da autenticação:

json

{
  "errors": "The PUT method is not supported for route api/v1/pacotes/1. Supported methods: GET, HEAD.",
  "code": 405
}

Endpoints disponíveis

Método	Endpoint	Permissão do token	Resultado
`GET`	`/api/v1/pacotes`	`listar_pacote_api`	Lista paginada, até 500 pacotes por página
`GET`	`/api/v1/pacotes/{id}`	`listar_pacote_api`	Um pacote e sua composição

Importante

Escopo por produtor efetivo. As duas rotas filtram por pacotes.user_id = <id do produtor>. Igual a Clientes: quando o token pertence a uma subconta (funcionário vinculado a um produtor), a API sobe para o produtor pai e retorna os pacotes dele, não apenas os cadastrados sob a subconta.

Listar pacotes

GET

bash

curl --request GET \
  --url 'https://ev.paylog.cash/api/v1/pacotes?status=1&nome=Kit&page=1' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

http

GET /api/v1/pacotes?status=1&nome=Kit&page=1 HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN

Parâmetros de consulta

Campo	Tipo	Obrigatório	Comportamento atual
`page`	inteiro	Não	Página solicitada. Quando omitido, usa `1`.
`status`	inteiro	Não	Filtra pelo código exato. Quando omitido, usa pacote ativo (`1`).
`nome`	string	Não	Busca parcial por nome com `LIKE %valor%`.
`data_inicio`	data	Não	Inclui pacotes com `created_at` a partir da data. Recomenda-se `YYYY-MM-DD`.
`data_fim`	data	Não	Inclui pacotes com `created_at` até o fim da data. Recomenda-se `YYYY-MM-DD`.
`codigo_referencia`	string	Não	Filtra pela referência externa em `pacotes_referencias.codigo_plataforma`.
`plataforma`	inteiro	Não	Filtra pelo código da plataforma em `pacotes_referencias.plataforma`. Pode ser combinado com `codigo_referencia`.

Observação

Consulte Status de pacotes e produtos para os códigos 0, 1 e 2. data_inicio e data_fim podem ser usados separadamente ou em conjunto; o primeiro considera o início do dia e o segundo, o fim do dia. Pacotes excluídos no painel (exclusão lógica) nunca aparecem na listagem.

Atenção

Dois comportamentos do filtro que costumam surpreender:

status vazio não é o mesmo que status omitido. O padrão 1 (ativo) só é aplicado quando o parâmetro não é enviado. Enviar ?status= compara com string vazia e devolve data: []. Omita o parâmetro em vez de enviá-lo vazio.
Enviar codigo_referencia ou plataforma restringe a pacotes que possuem referência externa. A simples presença de qualquer um dos dois parâmetros ativa a junção com pacotes_referencias, então pacotes sem nenhuma referência cadastrada saem do resultado — mesmo que o valor enviado esteja vazio.

Resposta `200`

json

{
  "current_page": 1,
  "data": [
    {
      "id": 1480,
      "nome": "Kit Exemplo API",
      "status": 1,
      "pacote_produtos": [
        {
          "id": 489,
          "nome": "Produto Exemplo API",
          "status": 1,
          "quantidade": 2
        }
      ]
    }
  ],
  "first_page_url": "https://ev.paylog.cash/api/v1/pacotes?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://ev.paylog.cash/api/v1/pacotes?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Anterior",
      "page": null,
      "active": false
    },
    {
      "url": "https://ev.paylog.cash/api/v1/pacotes?page=1",
      "label": "1",
      "page": 1,
      "active": true
    },
    {
      "url": null,
      "label": "Próxima &raquo;",
      "page": null,
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://ev.paylog.cash/api/v1/pacotes",
  "per_page": 500,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Campos de `data[]`

Campo	Tipo	Sempre retornado	Descrição
`id`	inteiro	Sim	ID numérico do pacote.
`nome`	string	Sim	Nome do pacote.
`status`	inteiro	Sim	Código de status do pacote.
`pacote_produtos`	array	Sim	Composição do pacote; pode ser `[]`. Este é o nome usado somente na listagem.
`pacote_produtos[].id`	inteiro	Condicional	ID do produto; presente em cada item da composição.
`pacote_produtos[].nome`	string	Condicional	Nome do produto; presente em cada item da composição.
`pacote_produtos[].status`	inteiro	Condicional	Status do produto; presente em cada item da composição.
`pacote_produtos[].quantidade`	inteiro	Condicional	Quantidade do produto dentro do pacote; presente em cada item da composição.

Importante

A composição muda de nome entre os dois endpoints. Em GET /api/v1/pacotes a chave é pacote_produtos; em GET /api/v1/pacotes/{id} a mesma coleção se chama produtos. O conteúdo de cada item é idêntico nos dois casos (id, nome, status, quantidade). Essa divergência de nome faz parte do contrato atual e não será "corrigida" sem aviso — leia a chave correta em cada endpoint.

Metadados da paginação

Campo	Tipo	Sempre retornado	Descrição
`current_page`	inteiro	Sim	Página atual.
`data`	array	Sim	Pacotes da página; pode ser `[]`.
`first_page_url`	string	Sim	URL da primeira página.
`from`	inteiro ou `null`	Sim	Posição do primeiro item; `null` quando vazio.
`last_page`	inteiro	Sim	Última página disponível.
`last_page_url`	string	Sim	URL da última página.
`links`	array	Sim	Links navegáveis da paginação.
`links[].url`	string ou `null`	Sim	URL do link; `null` quando indisponível.
`links[].label`	string	Sim	Rótulo HTML do link.
`links[].page`	inteiro ou `null`	Sim	Página do link.
`links[].active`	booleano	Sim	Indica a página atual.
`next_page_url`	string ou `null`	Sim	Próxima página, quando existir.
`path`	string	Sim	URL base da coleção.
`per_page`	inteiro	Sim	Limite fixo de `500` itens por página.
`prev_page_url`	string ou `null`	Sim	Página anterior, quando existir.
`to`	inteiro ou `null`	Sim	Posição do último item; `null` quando vazio.
`total`	inteiro	Sim	Total de pacotes encontrados.

Consultar um pacote

GET

bash

curl --request GET \
  --url 'https://ev.paylog.cash/api/v1/pacotes/1480' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

http

GET /api/v1/pacotes/1480 HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN

Parâmetro de rota

Campo	Tipo	Obrigatório	Descrição
`id`	inteiro	Sim	ID de um pacote pertencente ao produtor autenticado.

Resposta `200`

json

{
  "id": 1480,
  "nome": "Kit Exemplo API",
  "status": 1,
  "produtos": [
    {
      "id": 489,
      "nome": "Produto Exemplo API",
      "status": 1,
      "quantidade": 2
    }
  ]
}

Campo	Tipo	Sempre retornado	Descrição
`id`	inteiro	Sim	ID numérico do pacote.
`nome`	string	Sim	Nome do pacote.
`status`	inteiro	Sim	Código de status.
`produtos`	array	Sim	Composição do pacote; pode ser `[]`.
`produtos[].id`	inteiro	Condicional	ID do produto; presente em cada item da composição.
`produtos[].nome`	string	Condicional	Nome do produto; presente em cada item da composição.
`produtos[].status`	inteiro	Condicional	Status do produto; presente em cada item da composição.
`produtos[].quantidade`	inteiro	Condicional	Quantidade do produto no pacote; presente em cada item da composição.

Pacote ausente ou de outra conta

Os dois casos retornam a mesma resposta 404, sem revelar se o ID pertence a outro produtor.

json

{
  "message": "Não encontrado."
}

Exemplos de filtros

:::tabs --- Por nome

http

GET /api/v1/pacotes?nome=Kit HTTP/1.1

--- Por status

http

GET /api/v1/pacotes?status=2 HTTP/1.1

--- Por referência

http

GET /api/v1/pacotes?codigo_referencia=SKU-KIT-001&plataforma=13 HTTP/1.1

--- Desde uma data

http

GET /api/v1/pacotes?data_inicio=2026-07-01 HTTP/1.1

:::

Erros

Status	Corpo atual	Quando ocorre
`401`	`{ "message": "Unauthenticated." }`	Token ausente ou inválido.
`403`	`{ "errors": "User does not have the right permissions.", "code": 403 }`	Token sem `listar_pacote_api`.
`404`	`{ "message": "Não encontrado." }`	Pacote inexistente, excluído ou de outro produtor.
`405`	`{ "errors": "The PUT method is not supported for route api/v1/pacotes/1. Supported methods: GET, HEAD.", "code": 405 }`	Verbo não suportado. Ocorre antes da autenticação.
`500`	Texto `Algo deu errado!` (não é JSON)	Falha capturada pelo controlador — tipicamente `data_inicio` ou `data_fim` que o interpretador de datas não consegue converter.
`500`	`{ "message": "Server Error" }`	Falha não capturada pelo controlador (erro fatal de PHP, por exemplo composição que aponta para um produto removido do catálogo).

Importante

Existem dois formatos de 500 nesta rota: o do controlador é texto puro (Algo deu errado!), o do framework é JSON. Trate 500 pelo código HTTP, nunca pelo corpo. Os envelopes 403 e 405 usam as chaves errors (string) e code; o 404 usa message.

#Endpoints disponíveis

#Listar pacotes

#Parâmetros de consulta

#Resposta 200

#Campos de data[]

#Metadados da paginação

#Consultar um pacote

#Parâmetro de rota

#Resposta 200

#Pacote ausente ou de outra conta

#Exemplos de filtros

#Erros

Endpoints disponíveis

Listar pacotes

Parâmetros de consulta

Resposta `200`

Campos de `data[]`

Metadados da paginação

Consultar um pacote

Parâmetro de rota

Resposta `200`

Pacote ausente ou de outra conta

Exemplos de filtros

Erros